Quickstart

Alternatively, follow these steps to manually add ExpressCSV to an Angular 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 an Angular component for the importer

   import { Component } from '@angular/core';
   import { CSVImporter, x } from '@expresscsv/sdk';
   
   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'),
   });
   
   @Component({
     selector: 'app-import-products',
     standalone: true,
     template: `
       <button type="button" [disabled]="isOpen" (click)="openImporter()">
         Import Products
       </button>
     `,
   })
   export class ImportProductsComponent {
     isOpen = false;
   
     private importer = new CSVImporter({
       schema: productSchema,
       publishableKey: 'pk_test_...',
       importIdentifier: 'product-import',
       title: 'Import products',
     });
   
     openImporter() {
       this.isOpen = true;
   
       this.importer.open({
         chunkSize: 500,
         webhook: {
           url: 'http://localhost:4000/webhooks/products-import',
           headers: {
             Authorization: 'Bearer your-api-token',
           },
           metadata: {
             userId: 'user-123',
           },
         },
         onComplete: () => {
           this.isOpen = false;
         },
         onCancel: () => {
           this.isOpen = false;
         },
         onError: (error) => {
           this.isOpen = false;
           console.error('Import error', error);
         },
       });
     }
   }

4. Render the component from your app shell

   import { Component } from '@angular/core';
   import { ImportProductsComponent } from './import-products.component';
   
   @Component({
     selector: 'app-root',
     standalone: true,
     imports: [ImportProductsComponent],
     template: `<app-import-products />`,
   })
   export class AppComponent {}

5. Receive webhook deliveries in your backend

   Keep the schema in a shared or core package so both the Angular app 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