Migrate to v1

EdgeStore v1 is a deliberate major-version redesign. The browser router DX is largely unchanged, while direct API and privileged backend code now use API v2 semantics without a runtime v1 fallback.

Runtime and packages

• All packages are ESM-only and require Node.js 22.22.0 or newer.
• Zod is no longer a peer dependency. Bucket input accepts any Standard Schema library, including Zod, Valibot, and ArkType.
• @edgestore/server/core is removed. Import types such as InferClientOutputs from @edgestore/server.
• @edgestore/react/shared is removed. Import errors from @edgestore/react/errors.

Configure EdgeStore once

The HTTP handler and backend client now share the router's provider. The hosted provider is the default, so the basic handler setup stays the same. Replace initEdgeStoreClient({ router }) with router.client, and configure custom providers by chaining .provider(myProvider) on es.router(...).

import { initEdgeStore } from '@edgestore/server';
import { createEdgeStoreNextHandler } from '@edgestore/server/adapters/next/app';
import { initEdgeStoreClient } from '@edgestore/server/core';

const es = initEdgeStore.create();
const router = es.router({
  documents: es.fileBucket(),
});

export const handler = createEdgeStoreNextHandler({
  router,
});

export const backendClient = initEdgeStoreClient({
  router,
});

import { initEdgeStore } from '@edgestore/server';
import { createEdgeStoreNextHandler } from '@edgestore/server/adapters/next/app';

const es = initEdgeStore.create();
const router = es.router({
  documents: es.fileBucket(),
});

export const handler = createEdgeStoreNextHandler({
  router,
});

export const backendClient = router.client;

Breaking changes

Pagination is no longer page-number based. Continue only when your application intentionally needs another page:

const page = await backendClient.documents.listFiles({
  pagination: {
    currentPage: 1,
    pageSize: 50,
  },
});

const firstPage = await backendClient.documents.list({ limit: 50 });

const secondPage = firstPage.hasMore
  ? await backendClient.documents.list({
      cursor: firstPage.nextCursor ?? undefined,
      limit: 50,
    })
  : undefined;

const page = await backendClient.documents.list({ limit: 50 });

const deleted = await backendClient.documents.deleteMany({
  refs: page.items.map((file) => ({ id: file.id })),
});

for (const failure of deleted.failed) {
  console.error(failure.ref, failure.error.code);
}

Frontend route bodies and bucket input are now validated before any router hook or provider method runs. v0.8 did not validate upload input on the server, so requests that passed before can now fail with BAD_REQUEST. Hooks, paths, and metadata receive the schema's parsed output. The encrypted edgestore-ctx payload is also namespaced in v1; there is no decoder fallback for a v0.8 context cookie, so clients must complete the normal /init request after deployment.

Azure users must replace the reusable SAS token with the storage account key. The provider now derives short-lived create/write upload URLs and independent read-only URLs for private files. Canonical file URLs never include the credential query string.

Provider capabilities

Every provider is defined through the same resource-oriented contract. The router backend client exposes exactly the methods present on that provider:

Omitted capabilities are absent from TypeScript and are not replaced by a runtime fallback to the hosted API.

Staying on v0.8

v0.8 remains installable for applications that cannot migrate yet. Pin @edgestore/server and @edgestore/react to ^0.8.0 until you are ready.