How to import CSV files in WunderGraph

How to Import CSV Files in WunderGraph Using CSVBox

Integrating CSV import functionality into your WunderGraph application is a practical way to streamline data onboarding. Whether you’re building admin dashboards, internal tooling, or SaaS platforms, enabling users to upload spreadsheet data can enhance productivity and user experience.

This guide shows you step-by-step how to connect WunderGraph with CSVBox—a reliable CSV upload widget that handles validation, error display, and data ingestion at scale.

🧩 Who This Is For

This article is for:

• Full-stack developers using WunderGraph
• SaaS builders needing structured data import
• Teams building internal admin panels
• Engineers integrating user-submitted spreadsheet data

If you’re asking:

• “How do I allow users to upload CSVs in WunderGraph apps?”
• “What’s the best way to validate CSV imports before writing to my DB?”
• “How can I map columns and catch import errors before storage?”

Then this guide is for you.

✅ Why Add CSV Upload to WunderGraph?

WunderGraph excels at composing secure APIs from multiple sources. But raw CSV file handling—including validating structure, managing column mappings, and catching errors—is not built in.

Common developer challenges:

• Users want to import data via spreadsheets
• Manual CSV parsing leads to bugs and bad UX
• Manual validation and error handling becomes repetitive

With CSVBox, you get:

• A full-featured import widget with live spreadsheet preview
• Rich column-mapping and validation UI
• Scaled backend for processing large files
• Easy integration with WunderGraph mutations

🔧 Getting Started: What You’ll Need

Before diving in, make sure you have:

• A functioning WunderGraph frontend/backend setup
• A CSVBox account and active import “box” configured

Sign up at csvbox.io if you haven’t already.

🛠️ How to Integrate CSV Upload in WunderGraph

1. Create a WunderGraph App

If you’re starting from scratch:

npx create-wundergraph-app csv-import-demo
cd csv-import-demo
npm install
npm run dev

You now have a basic WunderGraph app running locally.

2. Set Up Your Import Box in CSVBox

Navigate to your CSVBox dashboard and:

• Create a new import box
• Define expected columns (e.g. name, email, age)
• Add validations (e.g. required fields, email format)
• Copy your client_app_id and import_link_id

These identifiers are used to embed the import widget in your frontend securely.

3. Install CSVBox React Widget

Inside your Next.js or React app, install the official widget:

npm install @csvbox/react

4. Embed the Widget Component

Create a dedicated component to host the uploader (e.g., CsvUploader.tsx):

import { CSVBox } from '@csvbox/react';

export default function CsvUploader() {
  const onData = (data) => {
    console.log("Received validated data from CSVBox", data);
    // Send to backend mutation
  };

  return (
    <CSVBox
      client_app_id="your-client-app-id"
      import_link_id="your-import-box-id"
      user={{ id: '123', name: 'Project Admin' }}
      onData={onData}
    />
  );
}

Use it in any page, like pages/index.tsx.

5. Create a WunderGraph Mutation to Receive CSV Data

Inside your WunderGraph operations folder:

// ./wundergraph.operations/importUsers.ts

import { createOperation } from '@wundergraph/sdk/server';

export default createOperation.mutation({
  input: z.object({
    users: z.array(
      z.object({
        name: z.string(),
        email: z.string().email(),
        age: z.number(),
      })
    ),
  }),
  handler: async ({ input }) => {
    for (const user of input.users) {
      console.log('Imported user:', user);
      // Insert into DB or trigger action
    }

    return {
      success: true,
      count: input.users.length,
    };
  },
});

This mutation accepts validated payloads from CSVBox and processes them.

6. Connect the Uploader to Your Backend

Update the CsvUploader component to trigger the mutation:

import { CSVBox } from '@csvbox/react';
import { useMutation } from '@wundergraph/nextjs';

export default function CsvUploader() {
  const { mutate } = useMutation.importUsers();

  const onData = async (data) => {
    const response = await mutate({ users: data });
    alert(`Imported ${response.count} users!`);
  };

  return (
    <CSVBox
      client_app_id="your-client-app-id"
      import_link_id="your-import-box-id"
      user={{ id: 'admin', name: 'Admin User' }}
      onData={onData}
    />
  );
}

Now CSV uploads are validated by CSVBox and inserted via a secure mutation.

🔁 Expected Data Shape

Ensure your CSV rows match the required format:

[
  { "name": "Alice", "email": "[email protected]", "age": 30 },
  { "name": "Bob", "email": "[email protected]", "age": 45 }
]

If the uploaded data doesn’t match the schema, CSVBox will show inline validation errors before onData is fired.

🧪 Common Problems and Fixes

✅ Why CSVBox Is Ideal for WunderGraph Apps

CSVBox handles the complex parts of csv-based data ingestion:

• Visual spreadsheet import UI
• Real-time schema validation
• Built-in column mapping
• Handles millions of rows
• Support for server-side webhooks

You can even bypass the frontend entirely and have CSVBox post clean data directly to your WunderGraph endpoint.

📘 Learn more: CSVBox Webhook Docs

🚀 Wrapping Up and Next Steps

By following this approach, you’ve added streamlined CSV import to your WunderGraph app—complete with type-safe operations and frontend validation.

You now support:

• Embedded CSV uploads via a secure UI
• Auto-validated payloads sent directly to your backend
• Clear schema management with zod validators

What you can do next:

• Persist imported data to your database
• Add notifications or confirmation UI post-import
• Use webhooks for analytics or downstream automation
• Secure data flow with auth-aware mutations

🔗 Helpful Resources

• CSVBox Documentation
• WunderGraph Operations Guide
• Complete CSVBox + WunderGraph Integration

Ready to empower your apps with reliable, user-friendly spreadsheet imports?
Start integrating CSVBox with WunderGraph today.