Create a new SpeziVibe app with customizable features
npm install create-spezivibe-appCreate a customized SpeziVibe health app template with the features you need.
``bash`
npx create-spezivibe-app my-health-app
Or run without a project name to be prompted:
`bash`
npx create-spezivibe-app
The CLI will prompt you to choose:
When you select Firebase, you'll be prompted to enter your Firebase credentials. Leave them blank to use the Firebase Emulator for local development.
When you select Medplum, configure your .env file with your Medplum project credentials (see Medplum Setup).
A customized Expo + React Native app with:
- Only the packages and features you selected
- Pre-configured .env.example and .env filesnpm install && npm start
- Firebase Emulator configuration (if Firebase selected)
- Clean git history
- Ready to run with
When you select Firebase without providing credentials, the app automatically uses the Firebase Emulator:
`bash`
cd my-health-app
npm install
npm run emulators # Start Firebase Emulator (Terminal 1)
npm start # Start Expo (Terminal 2)
No Firebase console setup needed for local development!
When you select the Medplum backend, configure your app for FHIR R4-compliant healthcare data:
1. Create a Medplum project at app.medplum.com
2. Create a Client Application (Project Admin → Clients)
3. Configure your .env file:
`bash`
EXPO_PUBLIC_BACKEND_TYPE=medplum
EXPO_PUBLIC_MEDPLUM_BASE_URL=https://api.medplum.com/
EXPO_PUBLIC_MEDPLUM_CLIENT_ID=your-client-id
EXPO_PUBLIC_MEDPLUM_PROJECT_ID=your-project-id
See @spezivibe/medplum for full documentation.
The CLI uses a plugin-based architecture with discoverable features:
1. Base Template (template/) - Core app structure with injection markersfeatures/*/manifest.json
2. Feature Manifests () - Declarative configuration for each featurecategory: "backend"
3. Backend Plugins - Features with are auto-discovered as backend options@spezivibe/*
4. Package Copying - Relevant packages from packages/
Each feature manifest can declare:
`json`
{
"name": "feature-name",
"description": "Human-readable description",
"category": "backend", // "backend" or "feature" (default)
"autoIncludes": ["onboarding"], // Features to auto-add when selected
"dependencies": {}, // NPM dependencies (@spezivibe/* auto-copied)
"scripts": {}, // NPM scripts to add
"copyDirs": [], // App-level directories to copy
"copyFiles": [], // Files to copy (won't overwrite)
"replaceFiles": [], // Files to replace (will overwrite)
"transforms": [], // Code transforms with markers
"envVars": {} // Environment variables
}
Package Auto-Inference: Dependencies starting with @spezivibe/ are automatically copied from packages/ and added to workspaces. For example, "@spezivibe/chat": "" will copy packages/chat to the generated project.
Features can provide different versions of files for different backends:
``
features/scheduler/
├── app/(tabs)/schedule.tsx # Default (local backend)
├── app/(tabs)/schedule.firebase.tsx # Used when Firebase is selected
The generator picks file.{backend}.tsx when that backend is selected, falling back to file.tsx otherwise.
To add a new backend (e.g., Supabase), create features/supabase/manifest.json:
`json`
{
"name": "supabase",
"category": "backend",
"description": "PostgreSQL backend with Supabase",
"autoIncludes": ["onboarding"],
"dependencies": {
"@spezivibe/account": "*",
"@supabase/supabase-js": "^2.0.0"
},
"envVars": { "EXPO_PUBLIC_SUPABASE_URL": "", "EXPO_PUBLIC_SUPABASE_ANON_KEY": "" }
}
No CLI code changes needed - it's auto-discovered! The @spezivibe/* packages are automatically copied from packages/.
`bashInstall dependencies
npm install
Testing
The CLI uses snapshot testing to catch regressions in generated projects:
- 30 snapshot tests covering 6 feature combinations
- Tests verify file structure and key file contents
- Run
npm run test:update after making intentional changes to update snapshotsProject Structure
`
cli/
├── src/
│ ├── index.ts # CLI entry point
│ ├── generator.ts # Project generation orchestrator
│ ├── prompts.ts # Interactive prompts
│ ├── config.ts # Feature discovery and configuration
│ ├── types.ts # TypeScript definitions
│ └── utils.ts # Dependency checking, verification
└── tests/
└── snapshot/ # Snapshot tests
├── generator.snapshot.test.ts
└── utils.ts
``MIT