# collection setup

Start with the parts you need. The service connects those parts to a provider; its configuration belongs to your app.

## 1. Initialize an app

Run this once in your app folder. An existing initialized Next.js app can skip it.

```
npx slices.sh install
```

## 2. 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 slices.sh add services
```

## 3. 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.10
```

## 4. 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 slices.sh add collection.memory
```

## Collection: 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 slices.sh add collection.memory
```

## Collection: 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 slices.sh add collection.mongodb
```

## Collection: 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 slices.sh add collection.neon
```

## Collection: 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 slices.sh add collection.supabase
```

## 5. 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.

## 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 dev
```