low-code-react-app-b/docs/guides/SEED_DATA_GUIDE.md

Seed Data System

Overview

The application now includes a comprehensive seed data system that loads initial data from JSON configuration into the database (KV store) on first launch.

Features

1. Automatic Data Loading

• Seed data is automatically loaded on application startup
• Only loads if data doesn't already exist (safe to re-run)
• All data is stored in the KV database for persistence

2. Seed Data Management UI

Navigate to Settings → Data tab to access the Seed Data Manager with three options:

• Load Seed Data: Populates database with initial data (only if not already loaded)
• Reset to Defaults: Overwrites all data with fresh seed data
• Clear All Data: Removes all data from the database (destructive action)

3. Dashboard Integration

The Project Dashboard displays available seed data including:

• Number of pre-configured files
• Number of sample models
• Number of example components
• And more...

Seed Data Contents

The system includes the following pre-configured data:

Files (project-files)

• Sample Next.js pages (page.tsx, layout.tsx)
• Material UI integration examples
• TypeScript configuration

Models (project-models)

• User model with authentication fields
• Post model with relationships
• Complete Prisma schema examples

Components (project-components)

• Button components with variants
• Card components with styling
• Reusable UI elements

Workflows (project-workflows)

• User registration flow
• Complete workflow with triggers and actions
• Visual workflow nodes and connections

Lambdas (project-lambdas)

• User data processing function
• HTTP trigger configuration
• Environment variable examples

Tests (project-playwright-tests, project-storybook-stories, project-unit-tests)

• E2E test examples
• Component story examples
• Unit test templates

Component Trees (project-component-trees)

• Application layout tree
• Nested component structures
• Material UI component hierarchies

Configuration

Adding New Seed Data

Edit /src/config/seed-data.json to add or modify seed data:

{
  "project-files": [...],
  "project-models": [...],
  "your-custom-key": [...]
}

Seed Data Schema

Each data type follows the TypeScript interfaces defined in /src/types/project.ts:

• ProjectFile
• PrismaModel
• ComponentNode
• Workflow
• Lambda
• PlaywrightTest
• StorybookStory
• UnitTest
• ComponentTree

API Reference

Hook: useSeedData()

import { useSeedData } from '@/hooks/data/use-seed-data'

const { isLoaded, isLoading, loadSeedData, resetSeedData, clearAllData } = useSeedData()

Returns:

• isLoaded: Boolean indicating if seed data has been loaded
• isLoading: Boolean indicating if an operation is in progress
• loadSeedData(): Function to load seed data (if not already loaded)
• resetSeedData(): Function to reset all data to seed defaults
• clearAllData(): Function to clear all data from database

Direct KV API

You can also interact with seed data directly:

// Get specific seed data
const files = await window.spark.kv.get('project-files')

// Update seed data
await window.spark.kv.set('project-files', updatedFiles)

// Delete seed data
await window.spark.kv.delete('project-files')

Components

<SeedDataManager />

Management UI for seed data operations (used in Settings → Data tab)

<SeedDataStatus />

Display component showing available seed data (used on Dashboard)

Best Practices

1. Always use the useKV hook for reactive state management
2. Use functional updates when modifying arrays/objects to prevent data loss
3. Test seed data thoroughly before deploying
4. Document custom seed data for team members
5. Keep seed data minimal - only include essential examples

Example: Custom Seed Data

// 1. Add to seed-data.json
{
  "my-custom-data": [
    { "id": "1", "name": "Example 1" },
    { "id": "2", "name": "Example 2" }
  ]
}

// 2. Use in component
import { useKV } from '@github/spark/hooks'

function MyComponent() {
  const [data, setData] = useKV('my-custom-data', [])
  
  // Always use functional updates
  const addItem = (newItem) => {
    setData(current => [...current, newItem])
  }
  
  return (
    <div>
      {data.map(item => (
        <div key={item.id}>{item.name}</div>
      ))}
    </div>
  )
}

Troubleshooting

Data Not Loading

• Check browser console for errors
• Verify seed-data.json is valid JSON
• Ensure data keys match KV store keys

Data Persisting After Clear

• Hard refresh the browser (Ctrl+Shift+R)
• Check for cached service workers (PWA)
• Verify clearAllData completed successfully

Type Errors

• Ensure seed data matches TypeScript interfaces
• Update types in /src/types/project.ts if needed
• Run type checking: npm run type-check

Future Enhancements

Planned improvements:

• Import/export seed data as JSON files
• Version control for seed data
• Seed data migration system
• Seed data validation UI
• Partial seed data loading