# file-storage 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/file-storage@^0.2.7
```

## 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 file-storage.local
```

## File storage: on this disk

Bytes under .data/files and a JSON index beside them, with nothing to provision. Uploads come through the app; multipart parts and trash receipts survive a restart. One process and one disk. URL options: buckets (list).

```
npx slices.sh add file-storage.local
```

## File storage: S3

Any S3-compatible store (AWS, Cloudflare R2, Backblaze B2, MinIO, Tigris) with the bucket as its own index and a presigned link straight to the browser. URL options: buckets (list).

```
npx slices.sh add file-storage.s3
```

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

## File storage: on this disk: setup note 1

Add .data/ to .gitignore: the bytes and the index live there.

## File storage: on this disk: setup note 2

This store lives on one disk. A serverless deployment loses the files between requests, so deploy with @slices.sh/file-storage.s3.

## File storage: on this disk: setup note 3

A screen works in a bucket, a private corner of the config ("files" by default). The config lists the ones its screens work in (`buckets`, which installs grow); list more, or a prefix such as "playground/", in `buckets` in services/file-storage/rules.ts. Any other is not-found.

## File storage: on this disk: setup note 4

Set maxUploadBytes and accept in services/file-storage/default.config.ts: nothing is capped until you do.

## File storage: S3: setup note 1

Set S3_BUCKET, S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY (and S3_ENDPOINT off AWS), or run npx extraorbital provision s3.

## File storage: S3: setup note 2

Give the bucket a CORS rule that lets your app's origin PUT and exposes ETag, or uploads fall back to going through the app: BACKEND.md has the JSON.

## File storage: S3: setup note 3

A screen works in a bucket, a private corner of the config ("files" by default). The config lists the ones its screens work in (`buckets`, which installs grow); list more, or a prefix such as "playground/", in `buckets` in services/file-storage/rules.ts. Any other is not-found.

## File storage: S3: setup note 4

Add a lifecycle rule that aborts incomplete multipart uploads and expires the __slices_multipart__/ prefix: BACKEND.md has the JSON.

## File storage: S3: setup note 5

Nothing is capped until you set maxUploadBytes and accept in services/file-storage/default.config.ts.

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