> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Module de stockage

Un contrat ObjectStorage, adaptateurs memory et compatible S3.

## Parcours pas à pas pour débuter

Prérequis : Lisez les deux guides pour débutants ci-dessous, terminez la configuration locale du Web et ouvrez ce monorepo à sa racine dans votre éditeur. Les paramètres Web appartiennent à `apps/web/.env.local` ; Next.js ne lit pas la racine `.env`. `/dashboard` dans le mode faux par défaut est une démo sans base de données ; `/auth` nécessite une base de données migrée.

Termes rapides : un espace de travail est constitué des utilisateurs, des données et des paramètres distincts d'une équipe. Le serveur est le backend de confiance ; gardez les clés du fournisseur hors du code du navigateur et du téléphone. Une migration est une modification de base de données versionnée qui crée ou met à jour des tables. Un modèle d'IA est le moteur qui répond ; le catalogue de modèles est la liste du serveur des identifiants de modèles et des prix disponibles. Un fournisseur est un service externe tel qu'un service d'IA, de messagerie ou de facturation. Un droit est une subvention qui permet à un espace de travail d'utiliser une fonctionnalité. Un webhook est un message qu'un service envoie au URL d'un autre service.

1. Pour un essai sans autorisation, conservez `STORAGE_PROVIDER=memory`. Si cette extraction n'a aucun contrôle de téléchargement visible, demandez à votre agent de codage d'inspecter `apps/web/app/api/storage/avatar/route.ts`, `apps/web/app/api/storage/logo/route.ts`, `apps/web/app/api/storage/organization-logo/route.ts` et la page des paramètres correspondants avant de câbler un petit exemple d'image.

2. Pour vérifier la persistance, définissez `STORAGE_PROVIDER=s3`, `STORAGE_REGION` et `STORAGE_BUCKET` dans `apps/web/.env.local`, ajoutez localement les informations d'identification de test réservées au serveur et redémarrez.

3. L'image doit être rechargée depuis le stockage. Les fichiers mémoire disparaissent lorsque le processus redémarre ; pour les erreurs S3, vérifiez le bucket, le point de terminaison et la stratégie d’accès.

Pour le code personnalisé, commencez par le `prompts/README.md` fourni et copiez l'invite la plus proche : `prompts/new-app-screen.md` pour un écran d'application ou `prompts/new-landing-page.md` pour une page publique. Pour le travail sur un serveur, une base de données ou un fournisseur, confiez à votre agent de codage la tâche de ce guide et demandez-lui de lire les miroirs `AGENTS.md`, `.ai/PROJECT_CONTEXT.md` et `.ai/` correspondants ; inspectez les fichiers sources exacts nommés ici ; lister les fichiers et les vérifications avant de les modifier ; préserver la propriété de l'espace de travail et les secrets du serveur ; et je vous montre la différence. Indiquez-lui le comportement souhaité, les champs d'entrée et de sortie, les rôles autorisés, les succès et erreurs attendus, ainsi que le compte, le fournisseur ou l'appareil de test. Utilisez des exemples de valeurs ; ne collez jamais un vrai secret.

[Avant de commencer](https://supastack.dev/fr/docs/web/before-you-start.md)

[Bases du terminal](https://supastack.dev/fr/docs/web/terminal-basics.md)

[Configuration locale Web](https://supastack.dev/fr/docs/web/ship-in-5-minutes.md)

[Invites de l'agent et mémoire du projet](https://supastack.dev/fr/docs/web/agents.md)


## Choisir le backend de stockage

`STORAGE_PROVIDER=memory` est la valeur par défaut sans identifiants. `local` écrit les objets sur le disque dans `STORAGE_LOCAL_DIR` (`./.data/storage` par défaut, explicitement requis en production) et les diffuse via des URL signées par HMAC à expiration sur `/api/storage/local/[...key]` (`STORAGE_LOCAL_SIGNING_SECRET`, avec repli sur `AUTH_SECRET`) pour les déploiements sur serveur unique. `s3` utilise `apps/web/src/storage-runtime.ts` pour composer le client AWS SDK sur le contrat restreint `@supastack/storage`, prenant en charge Supabase Storage et MinIO avec les URL par chemin activées par défaut.

```
STORAGE_PROVIDER=s3
STORAGE_REGION=us-east-1
STORAGE_BUCKET=your-product-bucket
# Set STORAGE_ACCESS_KEY_ID and STORAGE_SECRET_ACCESS_KEY on the server.
# Optional: STORAGE_ENDPOINT, STORAGE_FORCE_PATH_STYLE, STORAGE_PUBLIC_BASE_URL
# Self-hosted single-server disk storage:
# STORAGE_PROVIDER=local
# STORAGE_LOCAL_DIR=./.data/storage
# STORAGE_LOCAL_SIGNING_SECRET=
```


## Réutiliser les frontières d’envoi

Les routes fournies couvrent les objets, les avatars, les logos de profil et les logos d’organisation sous `/api/storage/`. Elles résolvent l’identité et les permissions de l’espace de travail, puis valident le format du fichier avant le stockage. Examinez la limite de taille et de type de la route choisie au lieu d’accepter des clés d’objet arbitraires fournies par le client.

Les URL publiques servent à la présentation, pas à l’autorisation. Gardez le contenu protégé derrière la vérification de lecture de l’application et configurez la politique du bucket ou du CDN selon les données de votre produit.


## Tester le stockage réel

Testez les envois autorisés et refusés, le rejet du type MIME et de la taille, les chemins d’un autre espace de travail, les objets absents et les pannes du fournisseur. Le mode mémoire ne persiste pas entre les processus ; avant la publication, vérifiez l’envoi et la récupération avec le backend choisi.

[Configuration du stockage Supabase](https://supastack.dev/fr/docs/web/project-structure.md)

[Télécharger l'inventaire des itinéraires](https://supastack.dev/fr/docs/web/project-structure.md)


## Configuration et paramètres

packages/storage définit l'interface ObjectStorage — putObject, getObject et deleteObject sur des locators d'objets — avec MemoryObjectStorage pour les tests déterministes et S3CompatibleObjectStorage pour les buckets de production.

Les clés d'objets sont construites avec buildWorkspaceObjectKey et vérifiées avec assertWorkspaceObjectKey, donc chaque fichier stocké est namespacé par workspace et usage (avatar, fichier, logo). WorkspaceScopedStorageError se déclenche quand une clé échappe à son workspace.

```
interface ObjectStorage {
  putObject(input: PutObjectInput): Promise<StoredObject>
  getObject(locator: ObjectLocator): Promise<StoredObject | undefined>
  deleteObject(locator: ObjectLocator): Promise<boolean>
  getPublicUrl(locator: ObjectLocator): string
}

key = {workspaceId}/{purpose}/{safeName}
```


## Processus d’implémentation

Les routes applicatives résolvent le workspace, valident l'upload, construisent la clé scopée et appellent l'adaptateur — le stockage ne voit jamais un chemin client brut. Sélectionnez l'adaptateur dans l'environnement serveur via STORAGE_PROVIDER et ses identifiants.

Exposez les lectures par la même frontière d'autorisation ; ne servez des URLs publiques que pour les objets que le produit publie délibérément.


## Vérification et dépannage

MemoryObjectStorage garde les tests unitaires déterministes — assertionnez clés, types de contenu et refus inter-workspaces ici. Vérifiez l'adaptateur S3 via le chemin smoke opt-in contre un vrai bucket avant de shipper les uploads.


## Suivant

[Module API](https://supastack.dev/fr/docs/modules/api.md)