Bewaar en serveer bestanden met de JavaScript SDK
Dagelijkse opslagstromen met client.storage: bucketbeheer, uploads van één en meerdere delen, streaming downloads, HMAC ondertekende URL's en herstel van de prullenbak.
Emmerbeheer#
Een bucket groepeert bestanden en beslist of ze openbaar zijn. Voor het maken en verwijderen van buckets is de sleutel service_role vereist. Voor het weergeven van buckets is een aangemelde gebruiker of een service_role-sleutel vereist (de anonieme sleutel ontvangt 403 FORBIDDEN).
// Maak een openbare bucket aan (iedereen kan objecten lezen zonder API-sleutels)
await admin.storage.createBucket('avatars', { public: true })
// Maak een privébucket (alleen objecteigenaren of service_role kunnen lezen)
await admin.storage.createBucket('invoices', {
public: false,
fileSizeLimit: 10 * 1024 * 1024, // Limiet van 10 MiB per bestand
allowedMimeTypes: ['application/pdf'],
})
// Maak een lijst van toegankelijke buckets
const { data: buckets, error } = await admin.storage.listBuckets()
Een bucket accepteert ook fileSizeLimit (in bytes) en allowedMimeTypes. Een upload die te groot is, retourneert 413 PAYLOAD_TOO_LARGE en een type dat niet is toegestaan, retourneert 400 BAD_REQUEST.
Uploaden, downloaden, weergeven, verwijderen#
const bucket = aura.storage.from('invoices')
// Uploaden: een bestand, blob, buffer of Uint8Array
// Bestanden > 5 MiB worden automatisch opgesplitst in meerdelige delen
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
contentType: 'application/pdf',
onUploadProgress: (progress) => {
console.log(`Upload progress: ${progress.percentage}%`)
},
})
// → { sleutel, bucket, url, grootte, content_type, etag }
// Vervang een bestaand bestand dat eigendom is van de huidige gebruiker
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })
// Geef bestanden weer onder een voorvoegsel/map
const { data: files } = await bucket.list({ prefix: `${user.id}/` })
// Download het bestand als een BLOB
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)
// Stream downloaden zonder het hele bestand in het geheugen te laden
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()
// Een bestand verwijderen (standaard naar de prullenbak verplaatst met een bewaartermijn van 30 dagen)
await bucket.remove([`${user.id}/2026-10.pdf`])
// Permanente verwijdering (omzeilt de prullenbak en maakt onmiddellijk schijfquota vrij)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })
Belangrijkste runtime-gedrag:
- Het uploaden van een bestaand pad retourneert
409 CONFLICTtenzijupsert: trueis opgegeven. - Anonieme uploads worden afgewezen met
403 FORBIDDENop zowel privé als openbare buckets (voor schrijven is een geverifieerde JWT of servicesleutel vereist). - Bescherming tegen padovergang: paden die
..of illegale tekens bevatten, retourneren400 INVALID_PATHzonder onverwerkte uitzonderingen. - Gebruikersisolatie: één gebruiker kan geen bestanden overschrijven of verwijderen die eigendom zijn van een andere gebruiker (
owner_id = auth.uid()). Structureer paden met behulp van op de gebruiker gerichte mappen zoals${user.id}/....
Een bestand delen (openbare en ondertekende URL's)#
// 1. Publieke bucket: directe permanente URL (geserveerd zonder API-sleutels)
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png
// Forceer downloaden als bijlage met aangepaste bestandsnaam
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
download: 'avatar-ada.png',
})
// 2. Privébucket: HMAC ondertekende URL met configureerbare TTL
const { data, error } = await aura.storage.from('invoices').createSignedUrl(
`${user.id}/2026-10.pdf`,
300, // Geldig gedurende 300 seconden (5 minuten)
{ download: true }
)
// data.signedUrl en data.url bevatten de HMAC ondertekende URL
// 3. Directe browserupload zonder geheime sleutels bloot te leggen
// Serverzijde (service_role):
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
`${user.id}/document.pdf`,
600
)
// Browserclient (geen API-sleutel vereist):
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
contentType: 'application/pdf',
})
Ondertekende URL's verzegelen de HTTP-methode (GET of PUT), bucket, sleutel en vervaltijdstempel. Eenmaal verlopen of als het object is verwijderd, ontvangen verzoeken 403 FORBIDDEN.
Wie kan wat doen (Toegangsmatrix)#
| Actie | Anonieme sleutel (anon) | Ingelogde gebruiker (authenticated) | Servicerol (service_role) |
|---|---|---|---|
| Bestand in een openbare bucket lezen | Ja | Ja | Ja |
| Bestand lezen in een privébucket | Nee (403) | Alleen eigenaar (owner_id = auth.uid()) | Ja |
| Upload een nieuw bestand | Nee (403) | Ja (wordt eigenaar) | Ja |
Vervang (upsert) of verwijder | Nee (403) | Alleen eigenaar | Ja |
| Lijst met bestanden in een openbare bucket | Ja | Ja | Ja |
| Lijst met bestanden in een privé-bucket | Nee (403) | Alleen eigenaar (filter RLS) | Ja |
| Buckets maken, bijwerken of verwijderen | Nee (403) | Nee (403) | Ja |
| Nieuw ondertekende upload-URL's | Nee (403) | Nee (403) | Ja |
De eigenaar wordt geïdentificeerd door het onderwerp JWT (auth.uid()). Op zowel openbare als privé-buckets kunnen gebruikers de objecten van andere gebruikers niet overschrijven of vernietigen.
Verplaatsen, kopiëren, metadata en prullenbak#
// Kopieer een bestand (behoudt het originele inhoudstype en aangepaste metagegevens)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')
// Verplaats of hernoem een bestand
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')
// Metagegevens van objecten inspecteren (grootte, MIME-type, ETag, aangepaste metagegevens)
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')
// Lijst met items die zich momenteel in de prullenbak bevinden (bewaartijd van 30 dagen)
const { data: trashItems } = await admin.storage.from('invoices').listTrash()
// Een object uit de prullenbak herstellen
await admin.storage.from('invoices').restore('2026/final.pdf')
Voor real-time afbeeldingstransformaties (grootte wijzigen, formaatconversie, rotatie) raadpleegt u de Storage SDK Reference.