collection setup
Start with the parts you need. The service connects those parts to a provider; its configuration belongs to your app.
View as Markdown1. Initialize an app
Run this once in your app folder. An existing initialized Next.js app can skip it.
npx install2. Install the service registry
Add services/index.ts, the file `import "@/services"` loads: it registers every services/<service>/<config>.config.ts with @slices.sh/core. A provider setup writes the same file, so this step is for an app that has none yet. https://slices.sh/r/services.json
npx add services3. Install the headless library
Add the React parts with npm. Their styling and composition belong to your app.
npm install @slices.sh/collection@^0.1.6 @slices.sh/auth@^0.1.104. Install the service
Use the interactive installer below to choose a provider and its options. The command installs the packages, services/<service>/default.config.ts, services/index.ts and the API route. No hand-written fetch or provider wrapper is needed.
npx add collection.memoryCollection: in memory
Records kept in the Node process with nothing to set up, served through the app's own routes and scoped by rules.ts: the backend to build against, and the reference every other backend is held to. URL options: none.
npx add collection.memoryCollection: MongoDB
Records in MongoDB, served through the app's own routes and scoped by rules.ts, indexed on the fields each collection lets a query name. URL options: none.
npx add collection.mongodbCollection: Neon Postgres
Scoped JSON documents in Neon Postgres, served through the app's own routes and scoped by rules.ts, with keyset pagination, atomic writes and an in-process change bus. URL options: none.
npx add collection.neonCollection: Supabase Postgres
The same Postgres store as Neon, over Supabase's connection, served through the app's own routes and scoped by rules.ts. URL options: none.
npx add collection.supabase5. Load your configuration
In the client component using the headless parts, load the service registry before rendering a required Root. Keep the client directive first.
"use client"// services/index.ts comes from https://slices.sh/r/services.json (or any provider setup)import "@/services"6. Provisioning is included
The slices.sh installation command provisions the required resources automatically. Restart your development server after credentials change.
Collection: in memory: setup note 1
Rows are lost when the server restarts, and live updates reach only watchers in the process that wrote. Move on with npx slices.sh add collection.mongodb (or -neon, -supabase): services/collection/*.config.ts and rules.ts are yours and stay.
Collection: MongoDB: setup note 1
Set MONGODB_URI in .env.local (npx extraorbital provision mongo): a mongodb:// or mongodb+srv:// URI, credentials included. MONGODB_DB is optional: the database in the URI's path, else "app". The resource is read on the first request, so next build needs neither.
Collection: MongoDB: setup note 2
Live updates travel through the process that wrote: with several app servers, a change reaches only the watchers connected to the same one.
Collection: MongoDB: setup note 3
The filter grammar has no $regex or $where: the same filters run against every backend.
Collection: Neon Postgres: setup note 1
Set POSTGRES_URL in .env.local (npx extraorbital provision neon writes it): the pooled connection string. POSTGRES_URL_NON_POOLING, the direct one, is optional. The resource is read on the first request, so next build needs neither.
Collection: Neon Postgres: setup note 2
Tables are created lazily, one per collection. Notifications reach subscribers in this Node process; writes from other instances do not produce local events.
Collection: Neon Postgres: setup note 3
npx tsx services/collection/emit-rls-policies.ts > policies.sql prints rules.ts as row-level security policies for a client that reaches the database without the app. Nothing at runtime depends on it.
Collection: Supabase Postgres: setup note 1
Supabase is not provisioned by extraorbital: bring your own project and set SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY and SUPABASE_DB_URL in .env.local. The resource is read on the first request, so next build needs none of them.
Collection: Supabase Postgres: setup note 2
The provider connects through SUPABASE_DB_URL with the service role, so the app's rules decide; the emitted RLS policies are the second lock for direct PostgREST or browser clients. Tables are created lazily, one per collection, in the schema the config names (default public).
Collection: Supabase Postgres: setup note 3
npx tsx services/collection/emit-rls-policies.ts > policies.sql prints rules.ts as row-level security policies. Nothing at runtime depends on it.
7. Run your component
Required roots throw a setup error when no service is configured. A required capability can be named with enabled. Use enabled="optional" only when the feature is intentionally optional. Parts hide controls the configured provider cannot support.
npm run devConfigure your installation
Before you start
The steps below run in a Next.js app with shadcn set up (it has a components.json). In an existing Next.js app, such as one from create-next-app, set shadcn up first:
npx shadcn@latest init -t next -b base -p novaOr start fresh: the slices CLI creates the app and sets it up.
npx slices.sh installInstall the service registry
Adds services/index.ts, which import "@/services" loads. A provider setup writes the same file, so skip this if your app has one.
npx add servicesInstall the headless library
npmAdd the React parts to your app, then compose them with your own elements.
npm install @slices.sh/collectionImport from @slices.sh/collection/headless.
Install the service
Connect the parts to a provider. Skip this step if this service is already configured in your app.
npx add collection.memoryAdds service configuration and API routes to your app, with the provider dependencies. For a headless composition, add import "@/services" after "use client".
The slices CLI installs the service and provisions its required resources in one command.
Provider setup notes
- Rows are lost when the server restarts, and live updates reach only watchers in the process that wrote. Move on with npx shadcn@latest add @slices/collection.mongodb (or -neon, -supabase): services/collection/*.config.ts and rules.ts are yours and stay.