> ## Documentation Index
> Fetch the complete documentation index at: https://flatfileinc-remove-rss-json.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> create a new Space every time Flatfile is opened
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
Make a new directory.
```bash theme={"system"}
mkdir example-flatfile-vuejs-embed
```
Go into that directory.
```bash theme={"system"}
cd example-flatfile-vuejs-embed
```
Follow prompts from the `init` command.
```bash theme={"system"}
npm init
```
```bash theme={"system"}
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`.
```HTML index.html (full page) theme={"system"}
Vue
```
```CSS src/styles.css theme={"system"}
/* Styles for home page */
html,
body {
height: 100%;
margin: 0;
padding: 0;
font-family: sans-serif;
background: #090b2b;
color: #fff;
}
#app {
display: flex;
align-items: center;
justify-content: center;
height: 100%;
}
/* End of styles for home page */
:root {
--ff-primary-color: #4c48ef !important;
--ff-secondary-color: #616a7d !important;
--ff-text-color: #090b2b !important;
--ff-dialog-border-radius: 4px !important;
--ff-border-radius: 5px !important;
--ff-bg-fade: rgba(0, 0, 0, 0.2) !important;
}
/* The default mount element */
/* #flatfile_iFrameContainer {
} */
/* A div around the iframe that contains Flatfile */
/* .flatfile_iframe-wrapper {
} */
/* The actual iframe that contains Flatfile */
/* #flatfile_iframe {
} */
.flatfile-close-button {
display: none !important;
}
/* Begin style overrides for when Flatfile is displayed as a modal */
/* This class gets appended to the flatfile_iframe-wrapper div */
.flatfile_displayAsModal {
padding: 50px !important;
width: calc(100% - 100px) !important;
height: calc(100vh - 100px) !important;
}
.flatfile_iframe-wrapper.flatfile_displayAsModal {
background: var(--ff-bg-fade) !important;
}
/* The close button in top right to close modal */
.flatfile_displayAsModal .flatfile-close-button {
display: block !important;
margin: 20px !important;
}
/* The icon for the close button in top right to close modal */
.flatfile_displayAsModal .flatfile-close-button svg {
fill: var(--ff-secondary-color) !important;
}
/* The actual iframe that contains Flatfile */
.flatfile_displayAsModal #flatfile_iframe {
border-radius: var(--ff-border-radius);
}
/* Begin style overrides for when you cancel out of the Flatfile modal */
/* The outer container of the modal that opens when you cancel out of Flatfile */
.flatfile_outer-shell {
background-color: var(--ff-bg-fade) !important;
border-radius: var(--ff-border-radius) !important;
}
/* The inner container of the modal that opens when you cancel out of Flatfile */
/* .flatfile_inner-shell {
} */
/* The white box inside the modal that opens when you cancel out of Flatfile */
.flatfile_modal {
border-radius: var(--ff-dialog-border-radius) !important;
}
/* The container for the buttons you see in the close modal */
/* .flatfile_button-group {
} */
/* Style the buttons you see in the close modal */
/* .flatfile_button {
} */
/* The "yes, cancel" button you see in the close modal */
.flatfile_primary {
border: 1px solid var(--ff-primary-color) !important;
background-color: var(--ff-primary-color) !important;
color: #fff;
}
/* The "no, stay" button you see in the close modal */
.flatfile_secondary {
color: var(--ff-secondary-color) !important;
}
/* The heading text you see in the close modal */
.flatfile_modal-heading {
color: var(--ff-text-color) !important;
}
/* The description text you see in the close modal */
.flatfile_modal-text {
color: var(--ff-secondary-color) !important;
}
/* End style overrides for when you cancel out of the Flatfile modal */
/* End style overrides for when Flatfile is displayed as a modal */
/* The container of the error component */
/* .ff_error_container {
}*/
/* The heading text you see in the error component */
/* .ff_error_heading {
}*/
/* The description text you see in the error component */
/* .ff_error_text {
}*/
```
### 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](https://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`.
```bash .env theme={"system"}
# 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"
```
```JSON tsconfig.json theme={"system"}
{
"compilerOptions": {
"baseUrl": ".",
"module": "ESNext",
"target": "es2016",
"useDefineForClassFields": true,
"lib": ["ES2020", "ESNext", "DOM", "DOM.Iterable"],
"skipLibCheck": true,
"allowJs": true,
"strict": true,
"esModuleInterop": true,
"incremental": true,
"moduleResolution": "node",
"resolveJsonModule": true,
"forceConsistentCasingInFileNames": true,
},
"include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue"],
"references": [{ "path": "./tsconfig.node.json" }]
}
```
```JSON tsconfig.node.json theme={"system"}
{
"compilerOptions": {
"composite": true,
"skipLibCheck": true,
"module": "es2015",
"moduleResolution": "bundler",
"allowSyntheticDefaultImports": true
},
"include": ["vite.config.ts"]
}
```
```TypeScript vite.config.ts theme={"system"}
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
// https://vitejs.dev/config/
export default defineConfig({
plugins: [vue()],
});
```
### 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.
```HTML src/App.vue theme={"system"}
```
```TypeScript src/main.ts theme={"system"}
import { createApp } from "vue";
import App from "./App.vue";
createApp(App).mount("#app");
```
```TypeScript src/vite-env.d.ts theme={"system"}
///
```
```TypeScript src/shims-vue.d.ts theme={"system"}
declare module "*.vue";
```
### 4. Start your client
1. Update your package.json to include this script:
```JSON theme={"system"}
"scripts": {
"dev": "vite",
"build": "vue-tsc && vite build",
"preview": "vite preview"
},
```
2. Now, start your front end by heading to the terminal and running the
following command.
```bash theme={"system"}
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
```
3. 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.
```TypeScript src/config.ts theme={"system"}
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.
1. Add a `src/listener.ts` file with this simple `recordHook`.
2. 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](/learning-center/guides/handling-data)
```TypeScript src/listeners/listener.ts theme={"system"}
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.",
},
});
}
});
});
});
```
```JavaScript src/App.vue theme={"system"}
```
### 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](/learning-center/guides/theming).
```typescript theme={"system"}
themeConfig: {
root: {
primaryColor: "red",
textColor: "white",
logo: "https://images.ctfassets.net/hjneo4qi4goj/gL6Blz3kTPdZXWknuIDVx/7bb7c73d93b111ed542d2ed426b42fd5/flatfile.svg",
},
},
```
### 8. Add customizations
You can stop here or you can [view our full reference](../reference/common) to
see all the ways you can customize your importer.
## Example Project
Find this Vue.js example project in the Flatfile GitHub repository.
Clone the Flatfile Vue.js tutorial here.