# Quick Start ## Next.js Setup [](https://edgestore.dev/docs/quick-start#nextjs-setup "Direct link to Next.js Setup") ### Install [](https://edgestore.dev/docs/quick-start#install "Direct link to Install") Let's start by installing the required packages. - npm - pnpm - yarn ``` shell npm install @edgestore/server @edgestore/react zodCopy ``` ``` shell pnpm add @edgestore/server @edgestore/react zodCopy ``` ``` shell yarn add @edgestore/server @edgestore/react zodCopy ``` ### Environment Variables [](https://edgestore.dev/docs/quick-start#environment-variables "Direct link to Environment Variables") Then go to your [Dashboard](https://dashboard.edgestore.dev/), create a new project and copy the keys to your environment variables. ``` .env shell EDGE_STORE_ACCESS_KEY=your-access-key EDGE_STORE_SECRET_KEY=your-secret-keyCopy ``` caution Make sure you add `.env` to your `.gitignore` file. You don't want to commit your secrets keys to your repository. ### Backend [](https://edgestore.dev/docs/quick-start#backend "Direct link to Backend") Now we can create the backend code for our Next.js app. EdgeStore is compatible with both types of Next.js apps ( `pages router` and `app router`). The example below is the simplest bucket you can create with EdgeStore. Just a simple file bucket with no validation that will be accessible by anyone with the link. You can have multiple buckets in your app, each with its own configuration. - app - pages ``` src/app/api/edgestore/[...edgestore]/route.ts ts import { initEdgeStore } from '@edgestore/server'; import { createEdgeStoreNextHandler } from '@edgestore/server/adapters/next/app'; const es = initEdgeStore.create(); /** * This is the main router for the EdgeStore buckets. */ const edgeStoreRouter = es.router({ publicFiles: es.fileBucket(), }); const handler = createEdgeStoreNextHandler({ router: edgeStoreRouter, }); export { handler as GET, handler as POST }; /** * This type is used to create the type-safe client for the frontend. */ export type EdgeStoreRouter = typeof edgeStoreRouter;Copy ``` ``` src/pages/api/edgestore/[...edgestore].ts tsx import { initEdgeStore } from '@edgestore/server'; import { createEdgeStoreNextHandler } from '@edgestore/server/adapters/next/pages'; const es = initEdgeStore.create(); /** * This is the main router for the edgestore buckets. */ const edgeStoreRouter = es.router({ publicFiles: es.fileBucket(), }); export default createEdgeStoreNextHandler({ router: edgeStoreRouter, }); /** * This type is used to create the type-safe client for the frontend. */ export type EdgeStoreRouter = typeof edgeStoreRouter;Copy ``` ### Frontend [](https://edgestore.dev/docs/quick-start#frontend "Direct link to Frontend") Now let's initiate our context provider. - app - pages ``` src/lib/edgestore.ts tsx 'use client'; import { type EdgeStoreRouter } from '../app/api/edgestore/[...edgestore]/route'; import { createEdgeStoreProvider } from '@edgestore/react'; const { EdgeStoreProvider, useEdgeStore } = createEdgeStoreProvider(); export { EdgeStoreProvider, useEdgeStore };Copy ``` ``` src/lib/edgestore.ts tsx 'use client'; import { createEdgeStoreProvider } from '@edgestore/react'; import { type EdgeStoreRouter } from '../pages/api/edgestore/[...edgestore]'; const { EdgeStoreProvider, useEdgeStore } = createEdgeStoreProvider(); export { EdgeStoreProvider, useEdgeStore };Copy ``` And then wrap our app with the provider. - app - pages ``` src/app/layout.tsx tsx import { EdgeStoreProvider } from '../lib/edgestore'; import './globals.css'; // ... export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); }Copy ``` ``` src/pages/_app.tsx tsx import '../styles/globals.css'; import type { AppProps } from 'next/app'; import { EdgeStoreProvider } from '../lib/edgestore'; export default function App({ Component, pageProps }: AppProps) { return ( ); }Copy ``` ### Upload file [](https://edgestore.dev/docs/quick-start#upload-file "Direct link to Upload file") You can use the `useEdgeStore` hook to access type-safe frontend client and use it to upload files. ``` tsx 'use client'; import * as React from 'react'; import { useEdgeStore } from '../lib/edgestore'; export default function Page() { const [file, setFile] = React.useState(); const { edgestore } = useEdgeStore(); return (

{ setFile(e.target.files?.[0]); }} />

); }Copy ``` ### Replace file [](https://edgestore.dev/docs/quick-start#replace-file "Direct link to Replace file") By passing the `replaceTargetUrl` option, you can replace an existing file with a new one. It will automatically delete the old file after the upload is complete. You can also just upload the file using the same file name, but in that case, you might still see the old file for a while because of the CDN cache. ``` tsx const res = await edgestore.publicFiles.upload({ file, options: { replaceTargetUrl: oldFileUrl, }, // ... });Copy ``` ### Delete file [](https://edgestore.dev/docs/quick-start#delete-file "Direct link to Delete file") You can delete a file by passing its url to the `delete` method. To be able to delete a file from a client component like this, you will need to set the `beforeDelete` [lifecycle hook](https://edgestore.dev/docs/configuration#lifecycle-hooks) on the bucket. ``` tsx await edgestore.publicFiles.delete({ url: urlToDelete, });Copy ``` ### Cancel upload [](https://edgestore.dev/docs/quick-start#cancel-upload "Direct link to Cancel upload") To cancel an ongoing file upload, you can use an AbortController the same way you would use it to cancel a fetch request. ``` tsx // prepare a state for the AbortController const [abortController, setAbortController] = useState(); // ... // instantiate the AbortController and add the signal to the upload method const abortController = new AbortController(); setAbortController(abortController); const res = await edgestore.publicFiles.upload({ file, signal: abortController.signal, }); // ... // to cancel the upload, call the controller's abort method abortController?.abort();Copy ``` info When you cancel an upload, an `UploadAbortedError` will be thrown. You can catch this error and handle it as needed. For more information, check the [Error Handling](https://edgestore.dev/docs/error-handling) page. ### Temporary files [](https://edgestore.dev/docs/quick-start#temporary-files "Direct link to Temporary files") You can upload temporary files by passing the `temporary` option to the `upload` method. Temporary files will be automatically deleted after 24 hours if they are not confirmed. ``` tsx await edgestore.publicFiles.upload({ file: fileToUpload, options: { temporary: true, }, });Copy ``` To confirm a temporary file, you can use the `confirmUpload` method. ``` tsx await edgestore.publicFiles.confirmUpload({ url: urlToConfirm, });Copy ``` info You can check if a file is temporary in the dashboard. Temporary files are marked with a clock icon. ## Troubleshooting [](https://edgestore.dev/docs/quick-start#troubleshooting "Direct link to Troubleshooting") If you have any problems using EdgeStore, please check the [Troubleshooting](https://edgestore.dev/docs/troubleshooting) page. - [Next.js Setup](https://edgestore.dev/docs/quick-start#nextjs-setup) - [Install](https://edgestore.dev/docs/quick-start#install) - [Environment Variables](https://edgestore.dev/docs/quick-start#environment-variables) - [Backend](https://edgestore.dev/docs/quick-start#backend) - [Frontend](https://edgestore.dev/docs/quick-start#frontend) - [Upload file](https://edgestore.dev/docs/quick-start#upload-file) - [Replace file](https://edgestore.dev/docs/quick-start#replace-file) - [Delete file](https://edgestore.dev/docs/quick-start#delete-file) - [Cancel upload](https://edgestore.dev/docs/quick-start#cancel-upload) - [Temporary files](https://edgestore.dev/docs/quick-start#temporary-files) - [Troubleshooting](https://edgestore.dev/docs/quick-start#troubleshooting) [Skip to main content](https://edgestore.dev/docs/configuration#__docusaurus_skipToContent_fallback) On this page ## Bucket Types [](https://edgestore.dev/docs/configuration\#bucket-types "Direct link to Bucket Types") There are two types of file buckets: `IMAGE` and `FILE`. Both types of buckets work basically the same way, but the `IMAGE` bucket only accepts [certain mime types](https://edgestore.dev/docs/configuration#image-bucket-accepted-mime-types). IMAGE buckets automatically generate a thumbnail version of the image file if the file is bigger than 200px in width or height. In case a thumbnail was generated, the url will be included in the response of the upload request. ``` ts const edgeStoreRouter = es.router({ publicFiles: es.fileBucket(), publicImages: es.imageBucket(), });Copy ``` ## Basic File Validation [](https://edgestore.dev/docs/configuration\#basic-file-validation "Direct link to Basic File Validation") You can set the maximum file size and the accepted mime types for every file bucket. ``` ts const edgeStoreRouter = es.router({ publicFiles: es.fileBucket({ maxSize: 1024 * 1024 * 10, // 10MB accept: ['image/jpeg', 'image/png'], // wildcard also works: ['image/*'] }), });Copy ``` ## Context [](https://edgestore.dev/docs/configuration\#context "Direct link to Context") Many of the functions that you can use to configure your file buckets receive a `context` object as an argument. This object is generated by the `createContext` function that you pass to your router configuration. ``` ts import { initEdgeStore } from '@edgestore/server'; import { type CreateContextOptions, createEdgeStoreNextHandler, } from '@edgestore/server/adapters/next/app'; import { z } from 'zod'; type Context = { userId: string; userRole: 'admin' | 'user'; }; async function createContext({ req }: CreateContextOptions): Promise { const { id, role } = await getUserSession(req); // replace with your own session logic return { userId: id, userRole: role, }; } const es = initEdgeStore.context().create(); // ... export default createEdgeStoreNextHandler({ router: edgeStoreRouter, /** * The context is generated and saved to a cookie * in the first load of the page. */ createContext, });Copy ``` You might need to refresh the context (e.g. when the user logs in or logs out). You can do this by calling the `reset` function from the `useEdgeStore` hook. ``` tsx const { edgestore, reset } = useEdgeStore(); async function runAfterAuthChange() { await reset(); // this will re-run the createContext function }Copy ``` ## Metadata & File Path [](https://edgestore.dev/docs/configuration\#metadata--file-path "Direct link to Metadata & File Path") Every uploaded file can hold two types of data: `metadata` and `path`. You can use this data for access control or for filtering files. The `metadata` and `path` can be generated from the context ( `ctx`) or from the `input` of the upload request. ``` ts const edgeStoreRouter = es.router({ publicFiles: es .fileBucket() // this input will be required for every upload request .input( z.object({ category: z.string(), }), ) // e.g. /publicFiles/{category}/{author} .path(({ ctx, input }) => [\ { category: input.category },\ { author: ctx.userId },\ ]) // this metadata will be added to every file in this bucket .metadata(({ ctx, input }) => ({ userRole: ctx.userRole, })), });Copy ``` ## Lifecycle Hooks [](https://edgestore.dev/docs/configuration\#lifecycle-hooks "Direct link to Lifecycle Hooks") You can use the `beforeUpload` and `beforeDelete` hooks to allow or deny file uploads and deletions. The `beforeDelete` hook must be defined if you want to delete files directly from the client. ``` ts const edgeStoreRouter = es.router({ publicFiles: es .fileBucket() /** * return `true` to allow upload * By default every upload from your app is allowed. */ .beforeUpload(({ ctx, input, fileInfo }) => { console.log('beforeUpload', ctx, input, fileInfo); return true; // allow upload }) /** * return `true` to allow delete * This function must be defined if you want to delete files directly from the client. */ .beforeDelete(({ ctx, fileInfo }) => { console.log('beforeDelete', ctx, fileInfo); return true; // allow delete }), });Copy ``` ## Access Control (Experimental) [](https://edgestore.dev/docs/configuration\#access-control-experimental "Direct link to Access Control (Experimental)") You can use the `accessControl` function to add bucket level logic to allow or deny access to files. If you have ever used Prisma, you will probably notice that the structure of the `accessControl` function is similar to how you would write a Prisma query. If you set the `accessControl` function, your bucket will automatically be configured as a **protected bucket**. You cannot change a protected bucket to a public bucket after it has been created. The opposite is also true, you cannot change a public bucket to a protected bucket. To access files from a **protected bucket** the user will need a specific encrypted cookie generated in your server by the EdgeStore package. Which means that they will only be able to access the files from within your app. Sharing the url of a protected file will not work. The access control check is performed on an edge function without running any database queries, so you won't need to worry about bad performance on your protected files. ``` ts const filesBucket = es .fileBucket() .path(({ ctx }) => [{ author: ctx.userId }]) .accessControl({ OR: [\ {\ // this will make sure that only the author of the file can access it\ userId: { path: 'author' },\ },\ {\ // or if the user is an admin\ userRole: {\ eq: 'admin',\ }, // same as { userRole: 'admin' }\ },\ ], });Copy ``` Other available operators are: `eq`, `not`, `gt`, `gte`, `lt`, `lte`, `in`, `contains` Good to know The access control functionality uses third party cookies. Since third party cookies are not supported in localhost (without https), in development, all the protected files will be proxied through your app's api so that the cookies can be forwarded to the file request. Also, the `` component from `next/image` does not forward the cookies in the request, so protected images won't be displayed. You will need ot use the `` tag instead. ## Limit parallel uploads [](https://edgestore.dev/docs/configuration\#limit-parallel-uploads "Direct link to Limit parallel uploads") When creating the provider, you can set the maximum number of concurrent uploads. EdgeStore's context provider will take care of queuing the uploads and will automatically upload the next file when the previous one is finished. ``` ts const { EdgeStoreProvider, useEdgeStore } = createEdgeStoreProvider({ maxConcurrentUploads: 5, // default is 5 });Copy ``` ## Base Path [](https://edgestore.dev/docs/configuration\#base-path "Direct link to Base Path") In case your app is not hosted at the root of your domain, you can specify the base path. If you set this, make sure to set the full path to the EdgeStore API. e.g. `/my-app/api/edgestore` or `https://example.com/my-app/api/edgestore` ``` tsx export default function App({ Component, pageProps }: AppProps) { return ( ); }Copy ``` ## IMAGE bucket accepted mime types [](https://edgestore.dev/docs/configuration\#image-bucket-accepted-mime-types "Direct link to IMAGE bucket accepted mime types") | mime type | | --- | | image/jpeg | | image/png | | image/gif | | image/webp | | image/svg+xml | | image/tiff | | image/bmp | | image/x-icon | - [Bucket Types](https://edgestore.dev/docs/configuration#bucket-types) - [Basic File Validation](https://edgestore.dev/docs/configuration#basic-file-validation) - [Context](https://edgestore.dev/docs/configuration#context) - [Metadata & File Path](https://edgestore.dev/docs/configuration#metadata--file-path) - [Lifecycle Hooks](https://edgestore.dev/docs/configuration#lifecycle-hooks) - [Access Control (Experimental)](https://edgestore.dev/docs/configuration#access-control-experimental) - [Limit parallel uploads](https://edgestore.dev/docs/configuration#limit-parallel-uploads) - [Base Path](https://edgestore.dev/docs/configuration#base-path) - [IMAGE bucket accepted mime types](https://edgestore.dev/docs/configuration#image-bucket-accepted-mime-types) [Skip to main content](https://edgestore.dev/docs/backend-client#__docusaurus_skipToContent_fallback) On this page # Backend Client Sometimes you might want to use the EdgeStore functionality directly from your backend. Things like deleting, uploading or even listing files can be done with the use of the backend client. ## Setup [](https://edgestore.dev/docs/backend-client\#setup "Direct link to Setup") You can use your EdgeStore router to initialize the backend client. Since Next.js doesn't allow exports in the api route, you will need to move your router to an external file. ``` src/lib/edgestore-server.ts ts import { initEdgeStoreClient } from '@edgestore/server/core'; // ... export const handler = createEdgeStoreNextHandler({ router: edgeStoreRouter, }); // ... export const backendClient = initEdgeStoreClient({ router: edgeStoreRouter, });Copy ``` Then you will need to update your api route to use the exported handler. ``` src/app/api/edgestore/[...edgestore]/route.ts ts import { handler } from '@/lib/edgestore-server'; export { handler as GET, handler as POST };Copy ``` example You can find an example of the backend client usage in the [next-advanced](https://github.com/edgestorejs/edgestore/tree/main/examples/next-advanced) example. ## Backend Upload [](https://edgestore.dev/docs/backend-client\#backend-upload "Direct link to Backend Upload") You can use the `upload` function to upload files from your backend. ### Upload a text file [](https://edgestore.dev/docs/backend-client\#upload-a-text-file "Direct link to Upload a text file") The simplest use case would be to just upload a `txt` file: ``` ts const res = await backendClient.publicFiles.upload({ content: 'some text content', });Copy ``` ### Upload a blob [](https://edgestore.dev/docs/backend-client\#upload-a-blob "Direct link to Upload a blob") You can also upload a more complex file using the Blob object. And there are also all the other options available in the normal upload. ``` ts const res = await backendClient.publicFiles.upload({ content: { blob: new Blob(['col1,col2,col2'], { type: 'text/csv' }), extension: 'csv', }, options: { temporary: true, }, ctx: { userId: '123', userRole: 'admin', }, input: { type: 'post', }, });Copy ``` ### Copy an existing file [](https://edgestore.dev/docs/backend-client\#copy-an-existing-file "Direct link to Copy an existing file") You can use an existing file's URL to copy it into the EdgeStore bucket. This can be an external file (from outside of EdgeStore) or an existing EdgeStore file. ``` ts const res = await backendClient.publicFiles.upload({ content: { url: 'https://some-url.com/file.txt', extension: 'txt', }, });Copy ``` ### Confirm a temporary file upload [](https://edgestore.dev/docs/backend-client\#confirm-a-temporary-file-upload "Direct link to Confirm a temporary file upload") If you upload a temporary file, you can confirm it by using the `confirmUpload` function. ``` ts const res = await backendClient.publicFiles.confirmUpload({ url: fileUrl, });Copy ``` ## Backend Delete [](https://edgestore.dev/docs/backend-client\#backend-delete "Direct link to Backend Delete") You can use the `deleteFile` function to delete files from your backend. ``` ts const res = await backendClient.publicFiles.deleteFile({ url: fileUrl, });Copy ``` ## Backend List Files (search) [](https://edgestore.dev/docs/backend-client\#backend-list-files-search "Direct link to Backend List Files (search)") You can use the `listFiles` function to list files from your backend. It's also possible to filter the results by path, metadata or upload timing. ``` ts // simple usage // get the first page (20 files) of all files in the bucket const res = await backendClient.publicFiles.listFiles(); // with filter and pagination const res = await backendClient.publicFiles.listFiles({ filter: { metadata: { role: 'admin', }, path: { type: 'post', }, uploadedAt: { gt: new Date(Date.now() - 1000 * 60 * 60 * 24 * 7), // past 7 days }, }, pagination: { currentPage: 1, // default: 1 pageSize: 50, // default: 20 (max: 100) }, });Copy ``` ## TypeScript Helpers [](https://edgestore.dev/docs/backend-client\#typescript-helpers "Direct link to TypeScript Helpers") Sometimes you might want to have the response type of the backend client functions, so you can use it to build your own functions. You can use the `InferClientResponse` helper type to infer the response type of the backend client. ``` src/lib/edgestore.ts ts import { type InferClientResponse } from '@edgestore/server/core'; // ... /** * This helper type can be used to infer the response type of the backend client */ export type ClientResponse = InferClientResponse;Copy ``` And you can use it like this: ``` ts export const getServerSideProps: GetServerSideProps<{ files: ClientResponse['publicFiles']['listFiles']['data']; }> = async () => { const res = await backendClient.publicFiles.listFiles(); return { props: { files: res.data } }; };Copy ``` - [Setup](https://edgestore.dev/docs/backend-client#setup) - [Backend Upload](https://edgestore.dev/docs/backend-client#backend-upload) - [Upload a text file](https://edgestore.dev/docs/backend-client#upload-a-text-file) - [Upload a blob](https://edgestore.dev/docs/backend-client#upload-a-blob) - [Copy an existing file](https://edgestore.dev/docs/backend-client#copy-an-existing-file) - [Confirm a temporary file upload](https://edgestore.dev/docs/backend-client#confirm-a-temporary-file-upload) - [Backend Delete](https://edgestore.dev/docs/backend-client#backend-delete) - [Backend List Files (search)](https://edgestore.dev/docs/backend-client#backend-list-files-search) - [TypeScript Helpers](https://edgestore.dev/docs/backend-client#typescript-helpers) [Skip to main content](https://edgestore.dev/docs/utils#__docusaurus_skipToContent_fallback) On this page ## Download links [](https://edgestore.dev/docs/utils#download-links "Direct link to Download links") Sometimes the browser shows the file directly in the browser instead of downloading it. To force the browser to download the file, you can use the `getDownloadUrl` function. ``` ts import { getDownloadUrl } from '@edgestore/react/utils'; getDownloadUrl( url, // the url of the file 'overwrite-file-name.jpg', // optional, the name of the file to download );Copy ``` ## Format file size [](https://edgestore.dev/docs/utils#format-file-size "Direct link to Format file size") You might want to display the file size in a human-readable format. You can use the `formatFileSize` function to do that. ``` ts import { formatFileSize } from '@edgestore/react/utils'; formatFileSize(10485760); // => 10MBCopy ``` - [Download links](https://edgestore.dev/docs/utils#download-links) - [Format file size](https://edgestore.dev/docs/utils#format-file-size) [Skip to main content](https://edgestore.dev/docs/error-handling#__docusaurus_skipToContent_fallback) On this page # Error Handling You might need to handle specific server errors in your application. Here is an example of how you can do that. ``` tsx import { EdgeStoreApiClientError, UploadAbortedError, } from '@edgestore/react/errors'; // ... Copy ``` ## Error Codes [](https://edgestore.dev/docs/error-handling\#error-codes "Direct link to Error Codes") - `BAD_REQUEST` - `FILE_TOO_LARGE` - `MIME_TYPE_NOT_ALLOWED` - `UNAUTHORIZED` - `UPLOAD_NOT_ALLOWED` - `DELETE_NOT_ALLOWED` - `CREATE_CONTEXT_ERROR` - `SERVER_ERROR` - [Error Codes](https://edgestore.dev/docs/error-handling#error-codes) [Skip to main content](https://edgestore.dev/docs/logging#__docusaurus_skipToContent_fallback) On this page # Logging The EdgeStore package outputs some logs on the server-side. You can configure the log level by passing the `logLevel` option when creating the api handler. You can set it to `debug` to see in more details what is happening in the server. ``` ts const handler = createEdgeStoreNextHandler({ logLevel: 'debug', // optional. defaults to 'error' in production and 'info' in development router: edgeStoreRouter, });Copy ``` ## Log Levels [](https://edgestore.dev/docs/logging\#log-levels "Direct link to Log Levels") - `debug` - `info` - `warn` - `error` - `none` - [Log Levels](https://edgestore.dev/docs/logging#log-levels) [Skip to main content](https://edgestore.dev/docs/troubleshooting#__docusaurus_skipToContent_fallback) On this page # Troubleshooting If you followed the docs to get started with EdgeStore, but you are having issues, here are some things you can try to find out what the problem might be. ## Check if the API is correctly configured [](https://edgestore.dev/docs/troubleshooting#check-if-the-api-is-correctly-configured "Direct link to Check if the API is correctly configured") You can try to access the `/health` endpoint of your edgestore API from the browser. The default URL is: [http://localhost:3000/api/edgestore/health](http://localhost:3000/api/edgestore/health) If you can see `OK` on the page, then the API is configured in the correct path. ## Set the log level to `debug` [](https://edgestore.dev/docs/troubleshooting#set-the-log-level-to-debug "Direct link to set-the-log-level-to-debug") You can set the [log level](https://edgestore.dev/docs/logging) to `debug` to see in more details what is happening in the server. (These logs are for the server-side and will not be visible in the browser console) ## Check the browser console and network tab [](https://edgestore.dev/docs/troubleshooting#check-the-browser-console-and-network-tab "Direct link to Check the browser console and network tab") Open the developer tools in your browser and check the console and network tab to see if there are any helpful error messages. ## Try to run one of the example apps [](https://edgestore.dev/docs/troubleshooting#try-to-run-one-of-the-example-apps "Direct link to Try to run one of the example apps") You can try to run one of the example apps on your local machine to see if it works. - clone the repo - `git clone https://github.com/edgestorejs/edgestore.git` - cd into the example app - `cd examples/next-basic` - install dependencies - `npm install` - add your environment variables - `examples/next-basic/.env.local` - run the app - `npm run dev` - access the app - [http://localhost:3000](http://localhost:3000/) There are [other example apps](https://github.com/edgestorejs/edgestore/tree/main/examples) that you can try. Try to find the one that is closer to your use case. # Tried everything and still not working? If you tried everything and still can't figure out what is wrong, you can reach for support in the [Discord server](https://discord.gg/HvrnhRTfgQ) or [open an issue](https://github.com/edgestorejs/edgestore/issues) in the GitHub repo. - [Check if the API is correctly configured](https://edgestore.dev/docs/troubleshooting#check-if-the-api-is-correctly-configured) - [Set the log level to `debug`](https://edgestore.dev/docs/troubleshooting#set-the-log-level-to-debug) - [Check the browser console and network tab](https://edgestore.dev/docs/troubleshooting#check-the-browser-console-and-network-tab) - [Try to run one of the example apps](https://edgestore.dev/docs/troubleshooting#try-to-run-one-of-the-example-apps) [Skip to main content](https://edgestore.dev/docs/components/image#__docusaurus_skipToContent_fallback) On this page # Single-image [See it in action](https://examples.edgestore.dev/components/single-image) drag & drop to upload select ## Usage [](https://edgestore.dev/docs/components/image\#usage "Direct link to Usage") ``` tsx 'use client'; import { SingleImageDropzone } from '@/components/SingleImageDropzone'; import { useEdgeStore } from '@/lib/edgestore'; import { useState } from 'react'; export function SingleImageDropzoneUsage() { const [file, setFile] = useState(); const { edgestore } = useEdgeStore(); return (

{ setFile(file); }} />

); }Copy ``` Expand ## Installation [](https://edgestore.dev/docs/components/image\#installation "Direct link to Installation") info This component uses tailwind for styling. Feel free to change `lucide-react` to any other icon library you prefer. First, let's install the required dependencies: - npm - pnpm - yarn ``` bash npm install tailwind-merge react-dropzone lucide-reactCopy ``` ``` bash pnpm add tailwind-merge react-dropzone lucide-reactCopy ``` ``` bash yarn add tailwind-merge react-dropzone lucide-reactCopy ``` Now just copy the following component into your components folder. ``` tsx 'use client'; import { formatFileSize } from '@edgestore/react/utils'; import { UploadCloudIcon, X } from 'lucide-react'; import * as React from 'react'; import { useDropzone, type DropzoneOptions } from 'react-dropzone'; import { twMerge } from 'tailwind-merge'; const variants = { base: 'relative rounded-md flex justify-center items-center flex-col cursor-pointer min-h-[150px] min-w-[200px] border border-dashed border-gray-400 dark:border-gray-300 transition-colors duration-200 ease-in-out', image: 'border-0 p-0 min-h-0 min-w-0 relative shadow-md bg-slate-200 dark:bg-slate-900 rounded-md', active: 'border-2', disabled: 'bg-gray-200 border-gray-300 cursor-default pointer-events-none bg-opacity-30 dark:bg-gray-700', accept: 'border border-blue-500 bg-blue-500 bg-opacity-10', reject: 'border border-red-700 bg-red-700 bg-opacity-10', }; type InputProps = { width: number; height: number; className?: string; value?: File | string; onChange?: (file?: File) => void | Promise; disabled?: boolean; dropzoneOptions?: Omit; }; const ERROR_MESSAGES = { fileTooLarge(maxSize: number) { return `The file is too large. Max size is ${formatFileSize(maxSize)}.`; }, fileInvalidType() { return 'Invalid file type.'; }, tooManyFiles(maxFiles: number) { return `You can only add ${maxFiles} file(s).`; }, fileNotSupported() { return 'The file is not supported.'; }, }; const SingleImageDropzone = React.forwardRef( ( { dropzoneOptions, width, height, value, className, disabled, onChange }, ref, ) => { const imageUrl = React.useMemo(() => { if (typeof value === 'string') { // in case an url is passed in, use it to display the image return value; } else if (value) { // in case a file is passed in, create a base64 url to display the image return URL.createObjectURL(value); } return null; }, [value]); // dropzone configuration const { getRootProps, getInputProps, acceptedFiles, fileRejections, isFocused, isDragAccept, isDragReject, } = useDropzone({ accept: { 'image/*': [] }, multiple: false, disabled, onDrop: (acceptedFiles) => { const file = acceptedFiles[0]; if (file) { void onChange?.(file); } }, ...dropzoneOptions, }); // styling const dropZoneClassName = React.useMemo( () => twMerge( variants.base, isFocused && variants.active, disabled && variants.disabled, imageUrl && variants.image, (isDragReject ?? fileRejections[0]) && variants.reject, isDragAccept && variants.accept, className, ).trim(), [\ isFocused,\ imageUrl,\ fileRejections,\ isDragAccept,\ isDragReject,\ disabled,\ className,\ ], ); // error validation messages const errorMessage = React.useMemo(() => { if (fileRejections[0]) { const { errors } = fileRejections[0]; if (errors[0]?.code === 'file-too-large') { return ERROR_MESSAGES.fileTooLarge(dropzoneOptions?.maxSize ?? 0); } else if (errors[0]?.code === 'file-invalid-type') { return ERROR_MESSAGES.fileInvalidType(); } else if (errors[0]?.code === 'too-many-files') { return ERROR_MESSAGES.tooManyFiles(dropzoneOptions?.maxFiles ?? 0); } else { return ERROR_MESSAGES.fileNotSupported(); } } return undefined; }, [fileRejections, dropzoneOptions]); return (

{/* Main File Input */} {imageUrl ? ( // Image Preview {acceptedFiles[0]?.name}

) : ( // Upload Icon

drag & drop to upload

)} {/* Remove Image Icon */} {imageUrl && !disabled && (

{ e.stopPropagation(); void onChange?.(undefined); }} >

)}

{/* Error Text */}

{errorMessage}

); }, ); SingleImageDropzone.displayName = 'SingleImageDropzone'; const Button = React.forwardRef< HTMLButtonElement, React.ButtonHTMLAttributes >(({ className, ...props }, ref) => { return ( )} {/* Error Text */}

{customError ?? errorMessage}

); }, ); MultiImageDropzone.displayName = 'MultiImageDropzone'; const Button = React.forwardRef< HTMLButtonElement, React.ButtonHTMLAttributes >(({ className, ...props }, ref) => { return ( ) : progress === 'ERROR' ? ( ) : progress !== 'COMPLETE' ? (

{abortController && ( )}

{Math.round(progress)}%

) : ( )} {/* Progress Bar */} {typeof progress === 'number' && (

)}

))} ); }, ); MultiFileDropzone.displayName = 'MultiFileDropzone'; export { MultiFileDropzone };Copy ``` Expand - [Usage](https://edgestore.dev/docs/components/multi-file#usage) - [Installation](https://edgestore.dev/docs/components/multi-file#installation) [Skip to main content](https://edgestore.dev/docs/express-adapter#__docusaurus_skipToContent_fallback) On this page # Express Adapter Some apps are built with React on the frontend (e.g. using `create-react-app` or `vite`) and have an `express.js` backend. You can also use EdgeStore in these cases, even without using Next.js. ## Setup [](https://edgestore.dev/docs/express-adapter\#setup "Direct link to Setup") ### Install [](https://edgestore.dev/docs/express-adapter\#install "Direct link to Install") Let's start by installing the required packages. - npm - pnpm - yarn ``` shell npm install @edgestore/server @edgestore/react zodCopy ``` ``` shell pnpm add @edgestore/server @edgestore/react zodCopy ``` ``` shell yarn add @edgestore/server @edgestore/react zodCopy ``` ### Environment Variables [](https://edgestore.dev/docs/express-adapter\#environment-variables "Direct link to Environment Variables") Then go to your [Dashboard](https://dashboard.edgestore.dev/), create a new project and copy the keys to your environment variables. ``` .env shell EDGE_STORE_ACCESS_KEY=your-access-key EDGE_STORE_SECRET_KEY=your-secret-keyCopy ``` caution Make sure you add `.env` to your `.gitignore` file. You don't want to commit your secrets keys to your repository. ### Backend [](https://edgestore.dev/docs/express-adapter\#backend "Direct link to Backend") Now we can create the backend code in our express app. The example below is the simplest bucket you can create with EdgeStore. Just a simple file bucket with no validation that will be accessible by anyone with the link. You can have multiple buckets in your app, each with its own configuration. ``` ts import { initEdgeStore } from '@edgestore/server'; import { createEdgeStoreExpressHandler } from '@edgestore/server/adapters/express'; import bodyParser from 'body-parser'; import cookieParser from 'cookie-parser'; import cors from 'cors'; import express from 'express'; // --- EXPRESS CONFIG --- const PORT = process.env.PORT ?? 3001; const app = express(); /** * Your express app is probably running in a different port than your frontend app. * To avoid CORS issues, we should use the cors middleware. */ app.use( cors({ credentials: true, origin: true, }), ); /** * EdgeStore uses cookies to store the context token. * We need to use the cookie parser middleware to parse the cookies. */ app.use(cookieParser()); /** * We need to have access to the json request body. * We can use the body parser middleware to parse the request. */ app.use(bodyParser.json()); // --- EDGESTORE ROUTER CONFIG --- const es = initEdgeStore.create(); const edgeStoreRouter = es.router({ publicFiles: es.fileBucket(), }); export type EdgeStoreRouter = typeof edgeStoreRouter; const handler = createEdgeStoreExpressHandler({ router: edgeStoreRouter, }); // --- EXPRESS ROUTES --- app.get('/', (req, res) => { console.log(req), res.send('Hello from server!'); }); // set the get and post routes for the edgestore router app.get('/edgestore/*', handler); app.post('/edgestore/*', handler); app.listen(PORT, () => { console.log(`⚡Server is running here 👉 http://localhost:${PORT}`); });Copy ``` ### Frontend [](https://edgestore.dev/docs/express-adapter\#frontend "Direct link to Frontend") Now let's initiate our context provider in the frontend app. ``` src/lib/edgestore.ts tsx // You can import it from the other project if it's just the type import { type EdgeStoreRouter } from '../../../path/to/express-backend/src'; import { createEdgeStoreProvider } from '@edgestore/react'; const { EdgeStoreProvider, useEdgeStore } = createEdgeStoreProvider(); export { EdgeStoreProvider, useEdgeStore };Copy ``` And then wrap our app with the provider. ``` src/App.tsx tsx import { EdgeStoreProvider } from '../lib/edgestore'; function App() { return ( {/* Rest of your app */} ); }Copy ``` ## Usage [](https://edgestore.dev/docs/express-adapter\#usage "Direct link to Usage") To upload or use the other functionalities of EdgeStore, you can look the main [Quick Start](https://edgestore.dev/docs/quick-start) guide. The usage should be the same. ## Limitations [](https://edgestore.dev/docs/express-adapter\#limitations "Direct link to Limitations") caution For EdgeStore to work properly in your deployed production app, Your frontend and backend should be in the same domain. If you are deploying to Vercel, you can take a look at the [Rewrites settings](https://vercel.com/docs/edge-network/rewrites). In case you are using Apache or Nginx, you can setup a reverse proxy to make sure your frontend and backend are in the same domain. - [Setup](https://edgestore.dev/docs/express-adapter#setup) - [Install](https://edgestore.dev/docs/express-adapter#install) - [Environment Variables](https://edgestore.dev/docs/express-adapter#environment-variables) - [Backend](https://edgestore.dev/docs/express-adapter#backend) - [Frontend](https://edgestore.dev/docs/express-adapter#frontend) - [Usage](https://edgestore.dev/docs/express-adapter#usage) - [Limitations](https://edgestore.dev/docs/express-adapter#limitations) [Skip to main content](https://edgestore.dev/docs/next-adapter#__docusaurus_skipToContent_fallback) # Next Adapter There are two adapters available for Next.js. The `next-app` (for the app-router) and the `next-pages` (for the pages-router). The steps to set up the adapter are in the main [Quick Start](https://edgestore.dev/docs/quick-start) guide. [Skip to main content](https://edgestore.dev/docs/tanstack-start-adapter#__docusaurus_skipToContent_fallback) On this page # TanStack Start Adapter TanStack Start integrates seamlessly with EdgeStore, enabling you to build type-safe, full-stack React applications with robust file management capabilities. ## Setup [](https://edgestore.dev/docs/tanstack-start-adapter#setup "Direct link to Setup") ### Install [](https://edgestore.dev/docs/tanstack-start-adapter#install "Direct link to Install") Let's start by installing the required packages. - npm - pnpm - yarn ``` shell npm install @edgestore/server @edgestore/react zodCopy ``` ``` shell pnpm add @edgestore/server @edgestore/react zodCopy ``` ``` shell yarn add @edgestore/server @edgestore/react zodCopy ``` ### Environment Variables [](https://edgestore.dev/docs/tanstack-start-adapter#environment-variables "Direct link to Environment Variables") Then go to your [Dashboard](https://dashboard.edgestore.dev/), create a new project and copy the keys to your environment variables. ``` .env shell EDGE_STORE_ACCESS_KEY=your-access-key EDGE_STORE_SECRET_KEY=your-secret-keyCopy ``` caution Make sure you add `.env` to your `.gitignore` file. You don't want to commit your secrets keys to your repository. ### Backend [](https://edgestore.dev/docs/tanstack-start-adapter#backend "Direct link to Backend") In your TanStack Start application, create an API route for EdgeStore with the following content: ``` app/routes/api/edgestore.$.ts ts import { initEdgeStore } from '@edgestore/server'; import { createEdgeStoreStartHandler } from '@edgestore/server/adapters/start'; import { createAPIFileRoute } from '@tanstack/start/api'; const es = initEdgeStore.create(); const edgeStoreRouter = es.router({ publicFiles: es.fileBucket(), }); export type EdgeStoreRouter = typeof edgeStoreRouter; const handler = createEdgeStoreStartHandler({ router: edgeStoreRouter, }); export const APIRoute = createAPIFileRoute('/api/edgestore/$')({ GET: handler, POST: handler, });Copy ``` ### Frontend [](https://edgestore.dev/docs/tanstack-start-adapter#frontend "Direct link to Frontend") Now let's initiate our context provider in the frontend app. ``` app/utils/edgestore.ts tsx import { createEdgeStoreProvider } from '@edgestore/react'; import { type EdgeStoreRouter } from '../routes/api/edgestore.$'; const { EdgeStoreProvider, useEdgeStore } = createEdgeStoreProvider(); export { EdgeStoreProvider, useEdgeStore };Copy ``` And then wrap our app with the provider. ``` app/routes/__root.tsx tsx import { EdgeStoreProvider } from '~/utils/edgestore'; // ... function RootComponent() { return ( ); }Copy ``` ## Usage [](https://edgestore.dev/docs/tanstack-start-adapter#usage "Direct link to Usage") To upload or use the other functionalities of EdgeStore, you can look the main [Quick Start](https://edgestore.dev/docs/quick-start) guide. The usage should be the same. - [Setup](https://edgestore.dev/docs/tanstack-start-adapter#setup) - [Install](https://edgestore.dev/docs/tanstack-start-adapter#install) - [Environment Variables](https://edgestore.dev/docs/tanstack-start-adapter#environment-variables) - [Backend](https://edgestore.dev/docs/tanstack-start-adapter#backend) - [Frontend](https://edgestore.dev/docs/tanstack-start-adapter#frontend) - [Usage](https://edgestore.dev/docs/tanstack-start-adapter#usage) [Skip to main content](https://edgestore.dev/docs/providers/edgestore#__docusaurus_skipToContent_fallback) On this page # EdgeStore Provider You can optionally pass in a provider to the `createEdgeStoreNextHandler` function. This is useful if you want to use a different provider than the default one or if you want to pass some custom options to the provider. The EdgeStore Provider is the default provider. If you followed the documentation, you already have it configured in your app. ``` ts import { initEdgeStore } from '@edgestore/server'; import { createEdgeStoreNextHandler, type CreateContextOptions, } from '@edgestore/server/adapters/next/pages'; import { EdgeStoreProvider } from '@edgestore/server/providers/edgestore'; import { z } from 'zod'; // ... export default createEdgeStoreNextHandler({ provider: EdgeStoreProvider(), // this is the default provider and can be omitted router: edgeStoreRouter, createContext, });Copy ``` ## Options [](https://edgestore.dev/docs/providers/edgestore#options "Direct link to Options") ``` ts export type EdgeStoreProviderOptions = { /** * Access key for your EdgeStore project. * Can be found in the EdgeStore dashboard. * * This can be omitted if the `EDGE_STORE_ACCESS_KEY` environment variable is set. */ accessKey?: string; /** * Secret key for your EdgeStore project. * Can be found in the EdgeStore dashboard. * * This can be omitted if the `EDGE_STORE_SECRET_KEY` environment variable is set. */ secretKey?: string; };Copy ``` - [Options](https://edgestore.dev/docs/providers/edgestore#options) [Skip to main content](https://edgestore.dev/docs/providers/aws#__docusaurus_skipToContent_fallback) On this page # AWS Provider You can also use the EdgeStore package with your own AWS S3 bucket. You might want to do that in case you have strict company policies that require you to have all the data in your own AWS account. You can also use the AWS Provider with other S3 compatible storage services like [Minio](https://min.io/). By using this provider, you will be able to use most of the basic features of EdgeStore. However, for some of the more advanced features like access control with protected files, you will have to create your own infrastructure and logic from scratch. ## Installation [](https://edgestore.dev/docs/providers/aws\#installation "Direct link to Installation") You need to install some peer dependencies to use this provider. ``` bash npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presignerCopy ``` Then you can set the provider in the router. ``` ts import { initEdgeStore } from '@edgestore/server'; import { createEdgeStoreNextHandler, type CreateContextOptions, } from '@edgestore/server/adapters/next/pages'; import { AWSProvider } from '@edgestore/server/providers/aws'; import { z } from 'zod'; // ... export default createEdgeStoreNextHandler({ provider: AWSProvider(), router: edgeStoreRouter, createContext, });Copy ``` ## Options [](https://edgestore.dev/docs/providers/aws\#options "Direct link to Options") ``` ts export type AWSProviderOptions = { /** * Access key for AWS credentials. * Can also be set via the `ES_AWS_ACCESS_KEY_ID` environment variable. * * If unset, the SDK will attempt to use the default credentials provider chain. */ accessKeyId?: string; /** * Secret access key for AWS credentials. * Can also be set via the `ES_AWS_SECRET_ACCESS_KEY` environment variable. * * If unset, the SDK will attempt to use the default credentials provider chain. */ secretAccessKey?: string; /** * AWS region to use. * Can also be set via the `ES_AWS_REGION` environment variable. */ region?: string; /** * Name of the S3 bucket to use. * Can also be set via the `ES_AWS_BUCKET_NAME` environment variable. */ bucketName?: string; /** * Custom endpoint for S3-compatible storage providers (e.g., MinIO). * Can also be set via the `ES_AWS_ENDPOINT` environment variable. */ endpoint?: string; /** * Force path style for S3-compatible storage providers. * Can also be set via the `ES_AWS_FORCE_PATH_STYLE` environment variable. * Defaults to false for AWS S3, but should be true for most S3-compatible providers. */ forcePathStyle?: boolean; /** * Base URL to use for accessing files. * Only needed if you are using a custom domain or cloudfront. * * Can also be set via the `EDGE_STORE_BASE_URL` environment variable. */ baseUrl?: string; /** * Secret to use for encrypting JWT tokens. * Can be generated with `openssl rand -base64 32`. * * Can also be set via the `EDGE_STORE_JWT_SECRET` environment variable. */ jwtSecret?: string; };Copy ``` ## Using with Minio [](https://edgestore.dev/docs/providers/aws\#using-with-minio "Direct link to Using with Minio") You can use the AWS Provider with Minio or other S3-compatible storage providers by setting the `endpoint` and `forcePathStyle` options. ``` ts provider: AWSProvider({ endpoint: 'http://localhost:9000', // can be set via the `ES_AWS_ENDPOINT` environment variable forcePathStyle: true, // can be set via the `ES_AWS_FORCE_PATH_STYLE` environment variable }),Copy ``` - [Installation](https://edgestore.dev/docs/providers/aws#installation) - [Options](https://edgestore.dev/docs/providers/aws#options) - [Using with Minio](https://edgestore.dev/docs/providers/aws#using-with-minio) [Skip to main content](https://edgestore.dev/docs/providers/azure#__docusaurus_skipToContent_fallback) On this page # Azure Provider You can also use the EdgeStore package with your own Azure Blob Storage. You might want to do that in case you have strict company policies that require you to have all the data in your own Azure account. By using this provider, you will be able to use most of the basic features of EdgeStore. However, for some of the more advanced features like access control with protected files, you will have to create your own infrastructure and logic from scratch. ## Installation [](https://edgestore.dev/docs/providers/azure\#installation "Direct link to Installation") You need to install some peer dependencies to use this provider. ``` bash npm install @azure/storage-blobCopy ``` Then you can set the provider in the router. ``` ts import { initEdgeStore } from '@edgestore/server'; import { createEdgeStoreNextHandler, type CreateContextOptions, } from '@edgestore/server/adapters/next/pages'; import { AzureProvider } from '@edgestore/server/providers/azure'; import { z } from 'zod'; // ... export default createEdgeStoreNextHandler({ provider: AzureProvider(), router: edgeStoreRouter, createContext, });Copy ``` ## Options [](https://edgestore.dev/docs/providers/azure\#options "Direct link to Options") ``` ts export type AzureProviderOptions = { /** * The storage account name for Azure Blob Storage * Can also be set via the `ES_AZURE_ACCOUNT_NAME` environment variable. */ storageAccountName?: string; /** * SAS token for Azure Blob Storage * Can also be set via the `ES_AZURE_SAS_TOKEN` environment variable. */ sasToken?: string; /** * Azure Blob Storage container name * Can also be set via the `ES_AZURE_CONTAINER_NAME` environment variable. */ containerName?: string; };Copy ``` - [Installation](https://edgestore.dev/docs/providers/azure#installation) - [Options](https://edgestore.dev/docs/providers/azure#options) [Skip to main content](https://edgestore.dev/docs/providers/custom#__docusaurus_skipToContent_fallback) # Custom Provider You can also create a custom provider for a different storage solution or just a different implementation for the existing providers. You can use the [EdgeStore Provider](https://github.com/edgestorejs/edgestore/blob/next/packages/server/src/providers/edgestore/index.ts) as a reference implementation. If you build a provider that you believe could be useful for others, please consider contributing it to the EdgeStore project by opening a pull request.