Skip to content
Sparkle Design System

Installation

Prerequisites

Section titled “Prerequisites”

Before installing Sparkle, ensure your development environment meets these requirements:

  • Node.js 18.0.0 or later (Download here)
  • pnpm 8.0.0 or later (recommended) or npm 8.0.0+
  • TypeScript 4.8 or later
  • React 18.0.0 or later

Installation Options

Section titled “Installation Options”

Choose the installation approach that fits your project:

Section titled “Option 1: Full Design System (Recommended)”

Install all core packages for complete design system functionality:

Terminal window
pnpm add @sparkle/ui @sparkle/theme @sparkle/types

This gives you:

  • ✅ Complete component library (@sparkle/ui)
  • ✅ Cross-platform design tokens (@sparkle/theme)
  • ✅ TypeScript definitions (@sparkle/types)

Option 2: Minimal Setup

Section titled “Option 2: Minimal Setup”

Install only what you need for a lightweight setup:

Terminal window
# Just design tokens for custom components
pnpm add @sparkle/theme @sparkle/types


# Add utilities for React hooks
pnpm add @sparkle/utils


# Add UI components when ready
pnpm add @sparkle/ui

Option 3: Development Setup

Section titled “Option 3: Development Setup”

For contributing to Sparkle or advanced debugging:

Terminal window
# Install development tools
pnpm add -D @sparkle/error-testing @sparkle/config


# Core packages
pnpm add @sparkle/ui @sparkle/theme @sparkle/types @sparkle/utils

Configuration

Section titled “Configuration”

1. Theme Provider Setup

Section titled “1. Theme Provider Setup”

Wrap your application with the Sparkle theme provider:

import { ThemeProvider } from '@sparkle/theme'
import { App } from './App'


function Root() {
  return (
    <ThemeProvider theme="light">
      <App />
    </ThemeProvider>
  )
}

2. Import Styles

Section titled “2. Import Styles”

Import Sparkle’s CSS in your main stylesheet or entry point:

/* Import Sparkle base styles */
@import '@sparkle/ui/styles.css';

3. TypeScript Configuration

Section titled “3. TypeScript Configuration”

Ensure your tsconfig.json includes proper module resolution:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "jsx": "react-jsx"
  }
}

Verification

Section titled “Verification”

Test your installation with a simple component:

import { useTheme } from '@sparkle/theme'
import { Button } from '@sparkle/ui'


function TestComponent() {
  const { theme, toggleTheme } = useTheme()


  return (
    <Button
      variant="primary"
      onClick={toggleTheme}
    >
      Current theme: {theme}
    </Button>
  )
}

Framework-Specific Setup

Section titled “Framework-Specific Setup”

Next.js

Section titled “Next.js”

Add to your next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@sparkle/ui', '@sparkle/theme'],
  experimental: {
    esmExternals: true,
  },
}


module.exports = nextConfig

Vite

Section titled “Vite”

Add to your vite.config.ts:

import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'


export default defineConfig({
  plugins: [react()],
  optimizeDeps: {
    include: ['@sparkle/ui', '@sparkle/theme'],
  },
})

Create React App

Section titled “Create React App”

CRA requires additional configuration for TypeScript paths and CSS imports. Consider migrating to Vite for better Sparkle support.

Troubleshooting

Section titled “Troubleshooting”

Common Issues

Section titled “Common Issues”
  • Module not found: Ensure you’ve installed all required packages
  • Type errors: Verify TypeScript configuration and @sparkle/types installation
  • Style issues: Check CSS import order and theme provider placement

Getting Help

Section titled “Getting Help”

Next Steps

Section titled “Next Steps”

Now that Sparkle is installed: