Installation

Recommended: Use the Installer

npx @spaceinvoices/react-ui@latest init
npx @spaceinvoices/react-ui@latest add customers/create-customer-form
npx @spaceinvoices/react-ui@latest add invoices/create-invoice-form

The published @spaceinvoices/react-ui package provides a shadcn-style installer that copies files into your project. The important part is still ownership: the generated result lives in your app, not behind a runtime abstraction.

Use the installer when you want a faster start. Use the manual path when you want maximum control over exactly what gets copied.

Manual Fallback

The React UI kit is designed for ownership, not package-style runtime installation. The manual workflow is still fully supported:

install the minimum dependencies
copy the files you need into your app
adjust imports to your aliases and UI primitives

Setup

1. Install Dependencies

Install Dependenciesbash

# Core requirements
npm install @spaceinvoices/js-sdk @tanstack/react-query

# For forms
npm install react-hook-form @hookform/resolvers zod

# UI components (use shadcn/ui)
npx shadcn@latest init
npx shadcn@latest add button input form table dialog select

2. Install UI Components (shadcn/ui)

# Initialize shadcn/ui if you haven't already
npx shadcn@latest init

# Add required components
npx shadcn@latest add button input form table dialog select card badge dropdown-menu popover calendar

Or use your existing UI library and update imports in copied components.

3. Clone the Repository

git clone https://github.com/space-invoices/react-ui.git

4. Copy What You Need

Copy Componentsbash

# Required: Core utilities and providers
cp -r react-ui/src/lib/ your-project/src/lib/
cp -r react-ui/src/providers/ your-project/src/providers/
cp -r react-ui/src/hooks/ your-project/src/hooks/

# Copy the components you need
cp -r react-ui/src/components/invoices/ your-project/src/components/space-invoices/
cp -r react-ui/src/components/customers/ your-project/src/components/space-invoices/
cp -r react-ui/src/components/items/ your-project/src/components/space-invoices/
cp -r react-ui/src/components/table/ your-project/src/components/space-invoices/

# DON'T copy components/ui/ - use shadcn/ui instead

5. Copy Generated Schemas

If you copy form components manually, also copy:

cp -r react-ui/src/generated/ your-project/src/generated/

6. Update Import Paths

Update Import Pathsbash

# Replace @/ui/ imports with your path alias
find your-project/src/components/space-invoices -type f -name "*.tsx" \
  -exec sed -i '' 's/@\/ui\//@\//g' {} +

# Or manually update imports in each file:
# Before: import { Button } from "@/ui/button"
# After:  import { Button } from "@/components/ui/button"

Minimum Working Install

If you want the smallest setup that still works cleanly, copy:

Path	Why
`src/providers/space-invoices-provider.tsx`	SDK runtime and auth wiring
`src/hooks/*.ts`	shared query/mutation helpers used by copied features
`src/lib/utils.ts`	shared `cn()` utility
`src/lib/translation.ts`	component-level i18n helper
`src/generated/schemas/*`	generated Zod schemas used by copied forms

Then add only the feature folders you actually need.

Source of Truth

the published installer lives in the standalone @spaceinvoices/react-ui package/repo
this monorepo contains the component source and registry metadata that feed that installer
both paths should result in owned application code, not a locked runtime dependency

Required Files

Always copy these core files:

Path	Purpose
`src/providers/space-invoices-provider.tsx`	Modular SDK runtime setup
`src/providers/entities-provider.tsx`	Active entity context
`src/hooks/*.ts`	Shared hooks
`src/lib/utils.ts`	`cn()` utility
`src/lib/translation.ts`	i18n helper
`src/generated/schemas/*`	Generated Zod schemas used by form components

Translations

The copy-paste components are designed to work without app-level i18n setup:

English/default strings should work out of the box
built-in locale files are optional overlays
your app can pass locale to use bundled translations where available
your app can pass t to override component wording with its own translation layer

So for a minimal install, you do not need to copy locale files unless you want built-in non-English copy immediately.

Optional Components

Copy only what you need:

Folder	Components
`components/invoices/`	Invoice forms and lists
`components/customers/`	Customer management
`components/items/`	Product/service catalog
`components/payments/`	Payment recording
`components/estimates/`	Estimates and proforma invoices
`components/dashboard/`	Charts and stats
`components/table/`	Data table infrastructure

Next Steps

Continue to Provider Setup to configure the recommended providers.