Quickstart

Alternatively, follow these steps to manually add ExpressCSV to a Vue app and receive imports in your existing backend.

1. Install the SDK

   npm

   pnpm

   yarn

   bun

   npm install @expresscsv/sdk

2. Get your publishable key

   You need a publishable key from the dashboard to connect the importer.

   New accounts start with two environments: Production and Development. For this example, grab the key from your Development environment.

3. Create a Vue component for the importer

   <script setup lang="ts">
   import { ref } from 'vue';
   import { CSVImporter, x } from '@expresscsv/sdk';
   
   const isOpen = ref(false);
   
   const productSchema = x.row({
     sku: x.string().label('SKU'),
     name: x.string().min(1).label('Product Name'),
     price: x.number().min(0).currency('USD').label('Price'),
   });
   
   const importer = new CSVImporter({
     schema: productSchema,
     publishableKey: 'pk_test_...',
     importIdentifier: 'product-import',
     title: 'Import products',
   });
   
   function openImporter() {
     isOpen.value = true;
   
     importer.open({
       chunkSize: 500,
       webhook: {
         url: 'http://localhost:4000/webhooks/products-import',
         headers: {
           Authorization: 'Bearer your-api-token',
         },
         metadata: {
           userId: 'user-123',
         },
       },
       onComplete: () => {
         isOpen.value = false;
       },
       onCancel: () => {
         isOpen.value = false;
       },
       onError: (error) => {
         isOpen.value = false;
         console.error('Import error', error);
       },
     });
   }
   </script>
   
   <template>
     <button type="button" :disabled="isOpen" @click="openImporter">
       Import Products
     </button>
   </template>

4. Render the button in your app

   <script setup lang="ts">
   import ImportProductsButton from './components/ImportProductsButton.vue';
   </script>
   
   <template>
     <ImportProductsButton />
   </template>

5. Receive webhook deliveries in your backend

   Keep the schema in a shared or core package so both the frontend and your backend can import it, then use @expresscsv/schemas to infer the webhook payload:

   import express from 'express';
   import type { InferWebhookPayload } from '@expresscsv/schemas';
   import { productSchema } from '../shared/product-schema';
   
   const app = express();
   app.use(express.json());
   
   app.post('/webhooks/products-import', async (req, res) => {
     const token = req.headers.authorization;
   
     if (token !== 'Bearer your-api-token') {
       return res.status(401).json({ error: 'Unauthorized' });
     }
   
     const payload = req.body as InferWebhookPayload<typeof productSchema>;
   
     console.log('Received import chunk', payload.records);
   
     return res.status(200).json({ ok: true });
   });
   
   app.listen(4000);

   Return a 2xx response for each chunk. 5xx and 429 responses are retried automatically, while other 4xx responses are treated as permanent failures.

6. Optional: disable preloading

   By default, the widget preloads in a hidden iframe so it opens instantly. To show a loading screen instead:

   const importer = new CSVImporter({
     schema: productSchema,
     publishableKey: 'pk_test_...',
     importIdentifier: 'product-import',
     preload: false,
   });

What's Next

• Types - define field types, validation rules, and TypeScript types
• Styling - theme the widget to match your app
• Webhooks - deliver records to your backend
• API Reference - full constructor, open(), and lifecycle reference