Quickstart

The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!

For synchronous data import/exchange completed in one session, create a new Space each time Flatfile is opened. This suits situations where a clean slate for every interaction is preferred.

Before you begin

Get your keys

To complete this tutorial, you'll need to retrieve your Publishable key from your development environment.

Note: The Publishable Key is safe to be used in client-side applications as it has limited access to the Flatfile API.

Make a new directory.

mkdir example-flatfile-vuejs-embed

Go into that directory.

cd example-flatfile-vuejs-embed

Follow prompts from the init command.

npm init

npm i vue @flatfile/vue @flatfile/plugin-record-hook @flatfile/listener && npm i --save-dev vite @vitejs/plugin-vue vue-tsc typescript

Create your file structure

Setup your app to look something like this:

├── src/
   ├── App.vue
   ├── config.ts
   ├── main.ts
   ├── shims-vue.d.ts (optional if you have errors when importing App.vue)
   ├── vite-env.d.ts
   ├── styles.css (optional)
   └── listener.ts (wait to add this)
├── index.html
├── tsconfig.json
├── tsconfig.node.json
├── vite.config.ts
├── .env (for your keys)
├── package.json <--- already created
└── package-lock.json <--- already created

In this file structure, your main directory is src.

Depending on how you want to handle styling your application, you can have a styles.css file in your src directory, create sub-directories to contain style files, or even create directories outside of src if you prefer. The only requirement is that the files can be imported into vue files.

The heart of your vue app will be App.vue, as this will configure and render your component(s) to the index.html.

Build your importer

1. Add a Flatfile Button

Add a button to your application to open Flatfile in a modal. Pass in your publishableKey and a new Space will be created on each page load. Optionally, add the content here to your styles.css.

  <!doctype html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>Vue</title>
    </head>
    <body>
      <div id="app"></div>
      <script type="module" src="/src/main.ts"></script>
    </body>
  </html>

2. Configure your project

In your environment file, you’ll need to define your keys. In this example, you will need your publishableKey. You can find these under “Developer settings” when logged into platform.flatfile.com.

You can create your .env file via the template below, as well as your App.vue, tsconfig.json, tsconfig.node.json, and vite.config.ts, which are the remaining top-level config files. After these are initialized properly we can configure the app files under src.

  # VITE_ is in front of these variables to make them accessible to App.vue
  VITE_ENVIRONMENT_ID = "your_environment_id"
  VITE_PUBLISHABLE_KEY = "your_publishable_key"

3. Initialize Flatfile

In your App.vue you’ll need to pass in a minimum of the publishableKey from your .env.

Also, add the content here to your main.ts, and vite-env.d.ts. Optionally you can also add shims-vue.d.ts if you have the need.

<script lang="jsx">
import { ref, defineComponent } from 'vue';
import { initializeFlatfile } from '@flatfile/vue';


export default defineComponent({
  setup() {
    const showSpace = ref(false);

    const spaceProps = ref({
      name: 'Vue Space',
      publishableKey: 'pk_1234',
      closeSpace: {
          operation: 'TestSheet:submit',
        onClose: () => { showSpace.value = false; },
      },
      workbook: {},
    });

    const { Space, OpenEmbed } = initializeFlatfile(spaceProps.value);

    const toggleSpace = () => {
      showSpace.value = !showSpace.value;
      OpenEmbed()
    };

    return {
      toggleSpace,
      showSpace,
      Space
    }
  },
  render(props, ctx) {
    const Space = props.Space

    return (
      <div>
        <div class="description">
          <button onClick={props.toggleSpace}>{ props.showSpace ? 'Close' : 'Open' } space</button>
        </div>

        {props.showSpace && <div class="space-wrapper">
          <Space />
        </div>}
      </div>
    )
  },
});
</script>

4. Start your client

Update your package.json to include this script:

  "scripts": {
    "dev": "vite",
    "build": "vue-tsc && vite build",
    "preview": "vite preview"
  },

Now, start your front end by heading to the terminal and running the following command.

  npm run dev

Your console should display a message like the following:

> vue@0.0.0 dev
> vite


  VITE v4.5.0  ready in 215 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

To view your app, copy the url and paste it into your browser. Click the button and see that an Empty Space gets created.

5. Build a workbook

Now, let’s build a Workbook inside the Space for next time.

Add your config.ts file, and place the following code in it. After you have done so, import the configuration to App.vue, and update spaceProps to have the value of config under workbook (this will be around line 36). This config file has the configuration settings for your workbook, so feel free to edit however necessary to meet your needs.

  import { Flatfile } from "@flatfile/api";

  export const config: Pick<
    Flatfile.CreateWorkbookConfig,
    "name" | "sheets" | "actions"
  > = {
    name: "Employees workbook",
    sheets: [
      {
        name: "TestSheet",
        slug: "TestSheet",
        fields: [
          {
            key: "first_name",
            type: "string",
            label: "First name",
            constraints: [
              {
                type: "required",
              },
            ],
          },
          {
            key: "last_name",
            type: "string",
            label: "last name",
          },
          {
            key: "email",
            type: "string",
            label: "Email",
          },
        ],
        actions: [
          {
            label: "Join fields",
            operation: "TestSheet:join-fields",
            description: "Would you like to join fields?",
            mode: "foreground",
            confirm: true,
          },
        ],
      },
    ],
    actions: [
      {
        label: "Submit",
        operation: "TestSheet:submit",
        description: "Would you like to submit your workbook?",
        mode: "foreground",
        primary: true,
        confirm: true,
      },
    ],
  };

6. Transform Data

Next, we’ll listen for data changes and respond using an event listener.

Add a src/listener.ts file with this simple recordHook.
Update App.tsx to import the listener.

Once you add this code, when a change occurs, we’ll log the entered first name and update the last name to “Rock.” You’ll immediately see this begin to work when you add or update any records. Learn more about Handling Data

import api from "@flatfile/api";
import { FlatfileListener } from "@flatfile/listener";
import { recordHook } from "@flatfile/plugin-record-hook";

/**
 * Example Listener
 */
export const listener = FlatfileListener.create((listener) => {
  listener.on("**", (event) => {
    //note: listening to all events with a wildcard can be used while testing but is not
    //recommended for production, as it will capture all events and may cause performance issues
    console.log(`Received event:`, event);
  });

  listener.use(
    recordHook("TestSheet", (record) => {
      const firstName = record.get("firstName");
      console.log({ firstName });
      record.set("lastName", "Rock");
      return record;
    })
  );

  listener.filter({ job: "workbook:TestSheet:submit" }, (configure) => {
    configure.on("job:ready", async ({ context: { jobId } }) => {
      try {
        await api.jobs.ack(jobId, {
          info: "Getting started.",
          progress: 10,
        });

        // Make changes after cells in a Sheet have been updated
        console.log("Make changes here when an action is clicked");

        await api.jobs.complete(jobId, {
          outcome: {
            acknowledge: true,
            message: "This is now complete.",
            next: {
              type: "wait",
            },
          },
        });
      } catch (error: any) {
        console.error("Error:", error.stack);

        await api.jobs.fail(jobId, {
          outcome: {
            message: "This job encountered an error.",
          },
        });
      }
    });
  });
});

7. Match your brand

By attaching a themeConfig to spaceProps in src/App.tsx, we will now override colors in your Space to match your brand. See all of the options here in the Theming Reference.

themeConfig: {
  root: {
    primaryColor: "red",
    textColor: "white",
    logo: "https://images.ctfassets.net/hjneo4qi4goj/gL6Blz3kTPdZXWknuIDVx/7bb7c73d93b111ed542d2ed426b42fd5/flatfile.svg",
  },
},

8. Add customizations

You can stop here or explore additional configuration options:

Common Configuration - Shared properties and basic configuration options
Simple Mode Configuration - Quick setup configurations for common use cases
Advanced Configuration - Advanced customizations and complex scenarios

Example Project

Find this Vue.js example project in the Flatfile GitHub repository.

create-flatfile-vuejs

Clone the Flatfile Vue.js tutorial here.

On this page

Before you begin
Get your keys
Create your file structure
Build your importer
1. Add a Flatfile Button
2. Configure your project
3. Initialize Flatfile
4. Start your client
5. Build a workbook
6. Transform Data
7. Match your brand
8. Add customizations
Example Project

The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!

For synchronous data import/exchange completed in one session, create a new Space each time Flatfile is opened. This suits situations where a clean slate for every interaction is preferred.

Before you begin

Get your keys

To complete this tutorial, you'll need to retrieve your Publishable key from your development environment.

Note: The Publishable Key is safe to be used in client-side applications as it has limited access to the Flatfile API.

Make a new directory.

mkdir example-flatfile-vuejs-embed

Go into that directory.

cd example-flatfile-vuejs-embed

Follow prompts from the init command.

npm init

npm i vue @flatfile/vue @flatfile/plugin-record-hook @flatfile/listener && npm i --save-dev vite @vitejs/plugin-vue vue-tsc typescript

Create your file structure

Setup your app to look something like this:

├── src/
   ├── App.vue
   ├── config.ts
   ├── main.ts
   ├── shims-vue.d.ts (optional if you have errors when importing App.vue)
   ├── vite-env.d.ts
   ├── styles.css (optional)
   └── listener.ts (wait to add this)
├── index.html
├── tsconfig.json
├── tsconfig.node.json
├── vite.config.ts
├── .env (for your keys)
├── package.json <--- already created
└── package-lock.json <--- already created

In this file structure, your main directory is src.

The heart of your vue app will be App.vue, as this will configure and render your component(s) to the index.html.

Build your importer

1. Add a Flatfile Button

Add a button to your application to open Flatfile in a modal. Pass in your publishableKey and a new Space will be created on each page load. Optionally, add the content here to your styles.css.

  <!doctype html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>Vue</title>
    </head>
    <body>
      <div id="app"></div>
      <script type="module" src="/src/main.ts"></script>
    </body>
  </html>

2. Configure your project

  # VITE_ is in front of these variables to make them accessible to App.vue
  VITE_ENVIRONMENT_ID = "your_environment_id"
  VITE_PUBLISHABLE_KEY = "your_publishable_key"

3. Initialize Flatfile

In your App.vue you’ll need to pass in a minimum of the publishableKey from your .env.

Also, add the content here to your main.ts, and vite-env.d.ts. Optionally you can also add shims-vue.d.ts if you have the need.

<script lang="jsx">
import { ref, defineComponent } from 'vue';
import { initializeFlatfile } from '@flatfile/vue';


export default defineComponent({
  setup() {
    const showSpace = ref(false);

    const spaceProps = ref({
      name: 'Vue Space',
      publishableKey: 'pk_1234',
      closeSpace: {
          operation: 'TestSheet:submit',
        onClose: () => { showSpace.value = false; },
      },
      workbook: {},
    });

    const { Space, OpenEmbed } = initializeFlatfile(spaceProps.value);

    const toggleSpace = () => {
      showSpace.value = !showSpace.value;
      OpenEmbed()
    };

    return {
      toggleSpace,
      showSpace,
      Space
    }
  },
  render(props, ctx) {
    const Space = props.Space

    return (
      <div>
        <div class="description">
          <button onClick={props.toggleSpace}>{ props.showSpace ? 'Close' : 'Open' } space</button>
        </div>

        {props.showSpace && <div class="space-wrapper">
          <Space />
        </div>}
      </div>
    )
  },
});
</script>

4. Start your client

Update your package.json to include this script:

  "scripts": {
    "dev": "vite",
    "build": "vue-tsc && vite build",
    "preview": "vite preview"
  },

Now, start your front end by heading to the terminal and running the following command.

  npm run dev

Your console should display a message like the following:

> vue@0.0.0 dev
> vite


  VITE v4.5.0  ready in 215 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

To view your app, copy the url and paste it into your browser. Click the button and see that an Empty Space gets created.

5. Build a workbook

Now, let’s build a Workbook inside the Space for next time.

  import { Flatfile } from "@flatfile/api";

  export const config: Pick<
    Flatfile.CreateWorkbookConfig,
    "name" | "sheets" | "actions"
  > = {
    name: "Employees workbook",
    sheets: [
      {
        name: "TestSheet",
        slug: "TestSheet",
        fields: [
          {
            key: "first_name",
            type: "string",
            label: "First name",
            constraints: [
              {
                type: "required",
              },
            ],
          },
          {
            key: "last_name",
            type: "string",
            label: "last name",
          },
          {
            key: "email",
            type: "string",
            label: "Email",
          },
        ],
        actions: [
          {
            label: "Join fields",
            operation: "TestSheet:join-fields",
            description: "Would you like to join fields?",
            mode: "foreground",
            confirm: true,
          },
        ],
      },
    ],
    actions: [
      {
        label: "Submit",
        operation: "TestSheet:submit",
        description: "Would you like to submit your workbook?",
        mode: "foreground",
        primary: true,
        confirm: true,
      },
    ],
  };

6. Transform Data

Next, we’ll listen for data changes and respond using an event listener.

Add a src/listener.ts file with this simple recordHook.
Update App.tsx to import the listener.

import api from "@flatfile/api";
import { FlatfileListener } from "@flatfile/listener";
import { recordHook } from "@flatfile/plugin-record-hook";

/**
 * Example Listener
 */
export const listener = FlatfileListener.create((listener) => {
  listener.on("**", (event) => {
    //note: listening to all events with a wildcard can be used while testing but is not
    //recommended for production, as it will capture all events and may cause performance issues
    console.log(`Received event:`, event);
  });

  listener.use(
    recordHook("TestSheet", (record) => {
      const firstName = record.get("firstName");
      console.log({ firstName });
      record.set("lastName", "Rock");
      return record;
    })
  );

  listener.filter({ job: "workbook:TestSheet:submit" }, (configure) => {
    configure.on("job:ready", async ({ context: { jobId } }) => {
      try {
        await api.jobs.ack(jobId, {
          info: "Getting started.",
          progress: 10,
        });

        // Make changes after cells in a Sheet have been updated
        console.log("Make changes here when an action is clicked");

        await api.jobs.complete(jobId, {
          outcome: {
            acknowledge: true,
            message: "This is now complete.",
            next: {
              type: "wait",
            },
          },
        });
      } catch (error: any) {
        console.error("Error:", error.stack);

        await api.jobs.fail(jobId, {
          outcome: {
            message: "This job encountered an error.",
          },
        });
      }
    });
  });
});

7. Match your brand

By attaching a themeConfig to spaceProps in src/App.tsx, we will now override colors in your Space to match your brand. See all of the options here in the Theming Reference.

themeConfig: {
  root: {
    primaryColor: "red",
    textColor: "white",
    logo: "https://images.ctfassets.net/hjneo4qi4goj/gL6Blz3kTPdZXWknuIDVx/7bb7c73d93b111ed542d2ed426b42fd5/flatfile.svg",
  },
},

8. Add customizations

You can stop here or explore additional configuration options:

Common Configuration - Shared properties and basic configuration options
Simple Mode Configuration - Quick setup configurations for common use cases
Advanced Configuration - Advanced customizations and complex scenarios

Example Project

Find this Vue.js example project in the Flatfile GitHub repository.

create-flatfile-vuejs

Clone the Flatfile Vue.js tutorial here.

On this page

Before you begin
Get your keys
Create your file structure
Build your importer
1. Add a Flatfile Button
2. Configure your project
3. Initialize Flatfile
4. Start your client
5. Build a workbook
6. Transform Data
7. Match your brand
8. Add customizations
Example Project

Before you begin

Get your keys

Create your file structure

Build your importer

1. Add a Flatfile Button

2. Configure your project

3. Initialize Flatfile

4. Start your client

5. Build a workbook

6. Transform Data

7. Match your brand

8. Add customizations

Example Project

create-flatfile-vuejs

Getting Started

Core Concepts

Plugins

Advanced Guides

Embedding Flatfile

Reference

Quickstart

Before you begin

Get your keys

Create your file structure

Build your importer

1. Add a Flatfile Button

2. Configure your project

3. Initialize Flatfile

4. Start your client

5. Build a workbook

6. Transform Data

7. Match your brand

8. Add customizations

Example Project

create-flatfile-vuejs

​Before you begin

​Get your keys

​Create your file structure

​Build your importer

​1. Add a Flatfile Button

​2. Configure your project

​3. Initialize Flatfile

​4. Start your client

​5. Build a workbook

​6. Transform Data

​7. Match your brand

​8. Add customizations

​Example Project

create-flatfile-vuejs

Getting Started

Core Concepts

Plugins

Advanced Guides

Embedding Flatfile

Reference

​Before you begin

​Get your keys

​Create your file structure

​Build your importer

​1. Add a Flatfile Button

​2. Configure your project

​3. Initialize Flatfile

​4. Start your client

​5. Build a workbook

​6. Transform Data

​7. Match your brand

​8. Add customizations

​Example Project

create-flatfile-vuejs

Before you begin

Get your keys

Create your file structure

Build your importer

1. Add a Flatfile Button

2. Configure your project

3. Initialize Flatfile

4. Start your client

5. Build a workbook

6. Transform Data

7. Match your brand

8. Add customizations

Example Project

Before you begin

Get your keys

Create your file structure

Build your importer

1. Add a Flatfile Button

2. Configure your project

3. Initialize Flatfile

4. Start your client

5. Build a workbook

6. Transform Data

7. Match your brand

8. Add customizations

Example Project