`:
```vue
```
`@nuxt/image` supports several built-in and third-party providers. Compatibility depends on the provider selected by the application.
Static source assets and remote providers that generate external image URLs do not require Easel-side transformation. Providers that expect a persistent local image server or provider-specific runtime behavior must be validated in a preview deployment.
Consult the image provider’s documentation before relying on dynamic image transformation in production.
Streaming [#streaming]
Nitro server routes can return streaming responses:
```ts title="server/api/stream.get.ts"
export default defineEventHandler(() => {
const encoder = new TextEncoder();
return new ReadableStream({
async start(controller) {
controller.enqueue(encoder.encode("Starting\n"));
await new Promise((resolve) => {
setTimeout(resolve, 500);
});
controller.enqueue(encoder.encode("Finished\n"));
controller.close();
},
});
});
```
Easel forwards response chunks as they are produced.
Streaming keeps the function invocation active until the stream closes. Long-running streams remain subject to the function’s maximum duration and connection limits.
Use a persistent service for indefinite connections.
Scheduled tasks [#scheduled-tasks]
Nitro scheduled tasks are not currently registered automatically as Easel schedules.
Expose the work through an authenticated server route:
```ts title="server/api/internal/cleanup.post.ts"
export default defineEventHandler(async (event) => {
const authorization = getRequestHeader(event, "authorization");
if (authorization !== `Bearer ${process.env.CRON_SECRET}`) {
throw createError({
statusCode: 401,
statusMessage: "Unauthorized",
});
}
await removeExpiredRecords();
return {
completed: true,
};
});
```
Invoke that route using an external scheduler.
The handler should be idempotent and should authenticate every scheduled request.
WebSockets [#websockets]
Easel Functions do not currently accept long-lived WebSocket upgrades.
Do not rely on Nitro WebSocket handlers for application traffic deployed through the standard Nuxt function path.
Use a dedicated WebSocket service or persistent application service for bidirectional connections.
Streaming HTTP responses and Server-Sent Events use a different transport and can work within function duration and connection limits.
Local filesystem [#local-filesystem]
The function filesystem is ephemeral.
Reading files bundled into the deployment is supported:
```ts
const contents = await useStorage("assets:server").getItem(
"templates/email.html",
);
```
Files created during an invocation are not guaranteed to exist on a later invocation or on another function instance.
Use object storage, a database, or another durable service for:
* User uploads
* Generated documents
* Session data
* Application state
* Persistent caches
Project configuration [#project-configuration]
Easel detects conventional Nuxt settings automatically:
| Setting | Default |
| ------------------- | --------------------------------- |
| Install command | Detected from the package manager |
| Build command | Package script or `nuxt build` |
| Output directory | Detected from Nitro output |
| Development command | Package script or `nuxt dev` |
| Node.js version | Project or platform default |
For monorepos, set the project root to the directory containing the Nuxt application’s `package.json` and `nuxt.config` file.
Do not commit `.output` as a substitute for running the production build unless your deployment workflow intentionally uses a prebuilt artifact.
Local development [#local-development]
Continue using Nuxt’s normal development server:
```bash
npm run dev
```
Nuxt development uses Nitro’s development runtime and provides hot module replacement for pages, components, server routes, and middleware.
Use an Easel preview deployment to validate platform-specific behavior, including:
* Production Nitro output
* Function execution
* Route-rule caching
* Prerendered routes
* Streaming
* Runtime environment variables
* Function duration and resource limits
* WAF and security rules
A preview deployment uses the same build and deployment path as production and receives its own immutable URL.
Known limitations [#known-limitations]
WebSockets [#websockets-1]
Long-lived WebSocket upgrades are not supported by the standard Easel Functions deployment path.
Scheduled tasks [#scheduled-tasks-1]
Nitro tasks are not converted automatically into Easel schedules. Use an authenticated server route and an external scheduler.
Persistent local storage [#persistent-local-storage]
Memory and local filesystem storage are scoped to individual function instances and may be discarded at any time.
Image providers [#image-providers]
`@nuxt/image` provider compatibility varies. Static images work normally, but dynamic providers that depend on platform-specific transformation infrastructure must be tested individually.
Provider-specific Nitro features [#provider-specific-nitro-features]
Features designed specifically for another Nitro deployment provider may not behave the same way on Easel.
Do not manually select another provider’s Nitro preset unless you are intentionally producing a prebuilt artifact whose output Easel supports.
Experimental features [#experimental-features]
Experimental Nuxt and Nitro features can change without maintaining the same deployment output. Validate them with a preview deployment before using them in production.
Troubleshooting [#troubleshooting]
Easel cannot find the server entry [#easel-cannot-find-the-server-entry]
Make sure the project runs `nuxt build`, not a custom command that replaces or moves the `.output` directory.
Remove manually configured `NITRO_PRESET`, `SERVER_PRESET`, or `nitro.preset` values unless they are specifically required by your deployment workflow.
The project deploys without server rendering [#the-project-deploys-without-server-rendering]
Confirm that the build command is `nuxt build` rather than `nuxt generate`.
Also check that `ssr: false` is not set globally or for the affected route.
A route rule does not apply [#a-route-rule-does-not-apply]
Confirm that the path pattern matches the deployed URL and that a more specific rule is not overriding it.
When using inline route rules, verify that the Nuxt experimental option required by your framework version is enabled. Define the rule in `nuxt.config` when the page path cannot be translated into a route-rule pattern.
A server environment variable is undefined [#a-server-environment-variable-is-undefined]
Confirm that the variable is configured for the current Easel environment.
For Nuxt runtime configuration, use the corresponding `NUXT_` environment-variable name. Preview and production environments can have different values.
Cached content does not update [#cached-content-does-not-update]
Check the applicable `cache`, `swr`, or `isr` route rule and confirm that the route is being served through the intended rendering path.
Deploy a preview and inspect the response headers, function logs, and cache activity.
Prerendering misses a route [#prerendering-misses-a-route]
Routes must either be listed explicitly, discovered through crawler links, or added programmatically during the build.
Dynamic routes that are not linked from another prerendered page generally need to be supplied explicitly.
Code works locally but fails after deployment [#code-works-locally-but-fails-after-deployment]
Run a preview deployment and inspect the production build and function logs.
Common causes include:
* Missing runtime environment variables
* Case-sensitive file paths
* Native dependencies incompatible with the function runtime
* Reliance on persistent local files
* A manually selected Nitro preset
* Build-time services that are inaccessible from Easel
* Provider-specific Nuxt modules
Compatibility policy [#compatibility-policy]
Easel tests its Nuxt integration against representative applications covering:
* Server-side rendering
* Client-side rendering
* Static generation
* Hybrid route rules
* API routes
* Server middleware
* Nitro plugins
* Streaming
* Runtime configuration
* Prerendering
* Response caching
* Redirects and headers
Stable Nuxt releases may work beyond the version listed at the top of this page, but the listed version is the most recently verified baseline.
For a newly released Nuxt version, Nitro version, module, image provider, or experimental feature, create a preview deployment before upgrading the production application.
# React Router on Easel
At a glance [#at-a-glance]
| | |
| ----------------------------- | --------------------------------------------- |
| **Support level** | Production-ready |
| **Supported versions** | React Router 7 and 8 |
| **Mode** | Framework Mode |
| **Rendering** | Static, SPA, SSR, streaming, and prerendering |
| **Server runtime** | Node.js |
| **Required preset** | `@vercel/react-router` |
| **Automatic detection** | Yes |
| **Most recently tested with** | React Router 8.3.x and 7.18.x |
React Router 8 is a non-breaking framework upgrade from React Router 7, but it raises the minimum versions of Node.js, React, and Vite. Existing React Router 7 applications can deploy without upgrading.
Version requirements [#version-requirements]
React Router 8 [#react-router-8]
React Router 8 requires:
* Node.js 22.22.0 or newer
* React 19.2.7 or newer
* Vite 7 or newer
* An ESM project
React Router 8 enables the behaviors previously introduced through React Router 7’s `future.v8_*` flags by default.
React Router 7 [#react-router-7]
React Router 7 supports older Node.js, React, and Vite baselines. Some newer framework behaviors, including stable middleware behavior, require future flags depending on the version you use.
For the most consistent migration path to React Router 8, enable the available `future.v8_*` flags and resolve any compatibility issues before upgrading.
Deploy a React Router application [#deploy-a-react-router-application]
Easel supports React Router applications using Framework Mode.
Install the deployment preset:
```bash
npm install -D @vercel/react-router
```
Add the preset to `react-router.config.ts`:
```ts title="react-router.config.ts"
import type { Config } from "@react-router/dev/config";
import { vercelPreset } from "@vercel/react-router/vite";
export default {
presets: [vercelPreset()],
} satisfies Config;
```
Then [create a project](/docs/getting-started) and connect the project’s Git repository, or [deploy with the CLI](/docs/cli/deploy):
```bash
easel deploy
```
Easel detects the React Router project, runs its production build, and provisions the static and server resources described by the generated deployment output.
You can override the install command, build command, root directory, Node.js version, and environment variables in your project settings.
Why run React Router on Easel? [#why-run-react-router-on-easel]
Easel provides a Vercel-compatible React Router deployment path with visible infrastructure, portable application conventions, and integrated edge services.
A React Router deployment includes:
* Immutable browser assets served through the Easel CDN
* Regional functions for server rendering, loaders, and actions
* Streaming HTTP responses
* Route-aware server bundles
* CDN caching controlled through standard response headers
* Preview deployments for branches and pull requests
* Built-in logs, metrics, traces, WAF, and attack protection
You can inspect deployed functions, request execution, cache behavior, and resource usage from the Easel dashboard.
What Easel deploys [#what-easel-deploys]
The React Router preset exposes the application’s route structure and generates the deployment output Easel consumes.
| React Router output | Easel resource |
| -------------------------- | ----------------------------- |
| Browser JavaScript and CSS | CDN assets |
| Public files | CDN assets |
| Prerendered pages | CDN assets |
| Server-rendered routes | Easel Functions |
| Loaders and actions | Easel Functions |
| Resource routes | Easel Functions |
| Server middleware | Application function pipeline |
| Streaming responses | Streaming function responses |
| SPA fallback | CDN routing configuration |
The preset allows server bundles to be split according to the application’s route structure rather than placing the entire server application in one undifferentiated function bundle.
Function CPU, memory, and duration remain controlled by Easel project settings
and framework route metadata (such as `maxDuration`). Functions run in US East.
Supported features [#supported-features]
| Feature | Support | Notes |
| ------------------------ | ------------- | --------------------------------------------------------------- |
| Framework Mode | Supported | Uses the React Router Vite plugin |
| React Router 8 | Supported | Requires the React Router 8 runtime baseline |
| React Router 7 | Supported | Future flags may be required for newer behavior |
| Server-side rendering | Supported | Dynamic document requests run in Easel Functions |
| Client-side navigation | Supported | Data requests are handled by the application function |
| Loaders | Supported | Run during document and applicable client-navigation requests |
| Actions | Supported | Handles mutations and form submissions |
| Nested routes | Supported | Includes nested layouts and data loading |
| Route error boundaries | Supported | Framework error responses are preserved |
| Streaming | Supported | Includes Suspense and deferred route data |
| Resource routes | Supported | Return JSON, files, feeds, and other non-UI responses |
| Server middleware | Supported | Stable in v8. Version-dependent setup in v7 |
| Client middleware | Supported | Runs in the browser during client navigations |
| Route context | Supported | Includes type-safe `RouterContextProvider` behavior |
| Static prerendering | Supported | Generated pages deploy to the CDN |
| SPA mode | Supported | Deploys a client-rendered application with route fallback |
| HTTP redirects | Supported | Includes redirects returned by loaders, actions, and middleware |
| Response headers | Supported | Includes route `headers` exports |
| Cookie sessions | Supported | Standard `Cookie` and `Set-Cookie` headers are preserved |
| File uploads | Supported | Subject to function request and duration limits |
| OpenTelemetry | Supported | Instrument application server code using standard SDKs |
| Custom server entry | Supported | Must expose the expected Web API request handler |
| WebSockets | Not supported | Function routes use HTTP request-response semantics |
| Persistent local storage | Not supported | Function filesystems are ephemeral |
Server rendering [#server-rendering]
Server rendering is enabled by default in Framework Mode.
A route can load data on the server and pass it to the component through generated route types:
```tsx title="app/routes/product.tsx"
import type { Route } from "./+types/product";
export async function loader({ params }: Route.LoaderArgs) {
const product = await getProduct(params.productId);
if (!product) {
throw new Response("Not found", {
status: 404,
});
}
return {
product,
};
}
export default function Product({
loaderData,
}: Route.ComponentProps) {
return (
{loaderData.product.name}
{loaderData.product.description}
);
}
```
For an initial document request, Easel invokes the application function and streams the rendered response to the client.
After hydration, React Router can request loader data without rerendering the complete document. Those data requests are routed to the same deployed application runtime.
Actions and forms [#actions-and-forms]
React Router actions handle mutations and form submissions:
```tsx title="app/routes/new-project.tsx"
import {
Form,
redirect,
} from "react-router";
import type { Route } from "./+types/new-project";
export async function action({
request,
}: Route.ActionArgs) {
const formData = await request.formData();
const project = await createProject({
name: String(formData.get("name")),
});
return redirect(`/projects/${project.id}`);
}
export default function NewProject() {
return (
);
}
```
The browser submits the form to the Easel Function running the React Router server application. Redirects, validation responses, cookies, and error boundaries continue through the framework’s normal response flow.
Streaming [#streaming]
React Router can begin returning a document before all asynchronous data is available.
A loader can return unresolved promises:
```tsx title="app/routes/dashboard.tsx"
import {
Await,
} from "react-router";
import { Suspense } from "react";
import type { Route } from "./+types/dashboard";
export async function loader() {
return {
account: await getAccount(),
activity: getRecentActivity(),
};
}
export default function Dashboard({
loaderData,
}: Route.ComponentProps) {
return (
{loaderData.account.name}
Loading activity…}>
{(activity) => (
)}
);
}
```
Easel forwards response chunks as React Router produces them rather than waiting for the entire render to finish.
The function remains active until the stream closes or the invocation reaches its maximum duration.
Middleware [#middleware]
React Router middleware can run before and after the matched route’s handlers.
Use middleware for authentication, request context, logging, instrumentation, response headers, and session handling.
```tsx title="app/routes/dashboard.tsx"
import {
createContext,
redirect,
} from "react-router";
import type { Route } from "./+types/dashboard";
type User = {
id: string;
email: string;
};
export const userContext = createContext();
const requireUser: Route.MiddlewareFunction =
async ({ request, context }, next) => {
const user = await authenticateRequest(request);
if (!user) {
throw redirect("/login");
}
context.set(userContext, user);
const response = await next();
response.headers.set("X-Authenticated", "true");
return response;
};
export const middleware: Route.MiddlewareFunction[] = [
requireUser,
];
export async function loader({
context,
}: Route.LoaderArgs) {
return {
user: context.get(userContext),
};
}
```
Server middleware runs inside the deployed React Router application function. It is distinct from Easel’s platform-level edge request pipeline and WAF.
Middleware in React Router 8 [#middleware-in-react-router-8]
Middleware behavior is enabled by default in React Router 8.
No `future.v8_middleware` flag is required.
Middleware in React Router 7 [#middleware-in-react-router-7]
React Router 7 versions that expose middleware behind a future flag require it in `react-router.config.ts`:
```ts title="react-router.config.ts"
import type { Config } from "@react-router/dev/config";
import { vercelPreset } from "@vercel/react-router/vite";
export default {
presets: [vercelPreset()],
future: {
v8_middleware: true,
},
} satisfies Config;
```
The exact future flags available depend on the installed React Router 7 release.
Request context [#request-context]
Use React Router’s context APIs to make request-specific dependencies available to middleware, loaders, and actions.
A custom server entry can seed the request context before React Router handles the request:
```ts title="app/entry.server.ts"
import {
createRequestHandler,
RouterContextProvider,
} from "react-router";
import { userContext } from "./context";
import * as build from "virtual:react-router/server-build";
const handleRequest = createRequestHandler(build);
export default async function handler(
request: Request,
) {
const context = new RouterContextProvider();
const user = await authenticateRequest(request);
if (user) {
context.set(userContext, user);
}
return handleRequest(request, context);
}
```
Use request context for dependencies that belong to one invocation, such as authenticated users, database transaction handles, request identifiers, or platform metadata.
Do not use module-level mutable state as a substitute for request context. A function instance may process multiple requests during its lifetime.
Resource routes [#resource-routes]
A route that does not export a default component can return a non-HTML response:
```ts title="app/routes/api.health.ts"
import type { Route } from "./+types/api-health";
export async function loader({
request,
}: Route.LoaderArgs) {
return Response.json({
ok: true,
timestamp: new Date().toISOString(),
});
}
```
Resource routes can return:
* JSON APIs
* XML and RSS feeds
* Generated files
* Redirects
* Streaming responses
* Webhook acknowledgements
They run within the same function execution model as document loaders and actions.
Response caching [#response-caching]
React Router does not impose one application caching policy. Routes can control browser and CDN behavior using standard HTTP response headers.
Export a `headers` function from a route:
```ts title="app/routes/products.tsx"
import type { Route } from "./+types/products";
export function headers(
_: Route.HeadersArgs,
) {
return {
"Cache-Control":
"public, s-maxage=60, stale-while-revalidate=300",
};
}
export async function loader() {
return {
products: await listProducts(),
};
}
```
In this example:
* Browsers follow the browser caching directives in the response
* Easel’s CDN can reuse the response for 60 seconds
* A stale response can remain available while it is refreshed for up to five minutes
Do not publicly cache responses containing user-specific or session-specific data.
For personalized routes, use:
```http
Cache-Control: private, no-store
```
A route’s caching policy should account for every header, cookie, query parameter, and authentication state that can change its response.
See [Cache responses at the edge](/docs/cdn/caching) and [Invalidate and revalidate cached content](/docs/cdn/revalidation).
Static prerendering [#static-prerendering]
React Router can generate selected routes during the production build.
Configure prerendered paths in `react-router.config.ts`:
```ts title="react-router.config.ts"
import type { Config } from "@react-router/dev/config";
import { vercelPreset } from "@vercel/react-router/vite";
export default {
presets: [vercelPreset()],
async prerender() {
return [
"/",
"/about",
"/pricing",
];
},
} satisfies Config;
```
Easel deploys the generated HTML and browser assets to the CDN.
Prerendered routes do not require a function invocation unless the application later navigates to server-backed data or another dynamic route.
React Router 8 uses its Vite environment-based prerendering flow. React Router 7 may use a version-dependent implementation, but the resulting static output is deployed through the same Easel path.
SPA mode [#spa-mode]
Set `ssr` to `false` to deploy a client-rendered single-page application:
```ts title="react-router.config.ts"
import type { Config } from "@react-router/dev/config";
import { vercelPreset } from "@vercel/react-router/vite";
export default {
ssr: false,
presets: [vercelPreset()],
} satisfies Config;
```
Easel deploys the generated browser application to the CDN and routes application paths to its SPA entry document.
In SPA mode:
* Route components run in the browser
* Server loaders and actions are unavailable
* `clientLoader` and `clientAction` remain available
* Static application assets are served without invoking a function
Use the [Vite guide](/docs/framework-guides/vite) instead when the application uses React Router only in Data Mode or Declarative Mode and does not use the Framework Mode build system.
Route module splitting [#route-module-splitting]
React Router can split route-module exports into smaller browser chunks so data and middleware code can load separately from component code.
React Router 8 enables its updated route-module behavior through top-level configuration and defaults inherited from the v8 release.
In compatible React Router 7 versions, the behavior may be enabled through a future flag:
```ts title="react-router.config.ts"
import type { Config } from "@react-router/dev/config";
import { vercelPreset } from "@vercel/react-router/vite";
export default {
presets: [vercelPreset()],
future: {
v8_splitRouteModules: true,
},
} satisfies Config;
```
This is primarily a browser-bundle optimization. Easel also uses the route information exposed by the deployment preset when constructing server bundles.
Sessions and cookies [#sessions-and-cookies]
React Router’s cookie and session APIs work through standard HTTP headers.
```ts title="app/sessions.server.ts"
import {
createCookieSessionStorage,
redirect,
} from "react-router";
const sessions = createCookieSessionStorage({
cookie: {
name: "__session",
httpOnly: true,
path: "/",
sameSite: "lax",
secrets: [process.env.SESSION_SECRET!],
secure: process.env.NODE_ENV === "production",
},
});
export async function action({
request,
}: {
request: Request;
}) {
const session = await sessions.getSession(
request.headers.get("Cookie"),
);
session.set("userId", "user_123");
return redirect("/dashboard", {
headers: {
"Set-Cookie":
await sessions.commitSession(session),
},
});
}
```
Cookie-backed sessions do not require server storage, but their contents are sent with each applicable request.
Use a database or durable key-value store for session state that is too large for a cookie, must be revoked centrally, or must be shared with other services.
Environment variables [#environment-variables]
Configure environment variables in the Easel dashboard or CLI.
Server-side variables are available to loaders, actions, middleware, resource routes, and server entry code:
```ts
const databaseUrl = process.env.DATABASE_URL;
```
Do not expose `process.env` directly to browser code.
When browser code needs public configuration, return an explicit allowlist from the root loader:
```tsx title="app/root.tsx"
import type { Route } from "./+types/root";
export async function loader() {
return {
env: {
PUBLIC_API_ORIGIN:
process.env.PUBLIC_API_ORIGIN,
},
};
}
export default function App({
loaderData,
}: Route.ComponentProps) {
return (
);
}
```
Only expose values that are safe for every visitor to read.
Use separate environment values for production, preview, and development deployments when necessary.
OpenTelemetry [#opentelemetry]
React Router server code runs in the Node.js application function and can use standard OpenTelemetry instrumentation.
Initialize instrumentation before handling application requests:
```ts
import { NodeSDK } from "@opentelemetry/sdk-node";
const sdk = new NodeSDK({
serviceName: "react-router-app",
});
sdk.start();
```
Easel can ingest application telemetry alongside function logs, request metrics, and platform traces.
Avoid starting a new SDK for each request. Initialize reusable instrumentation at module scope and attach request-specific data through spans or context.
Project configuration [#project-configuration]
Easel detects conventional React Router Framework Mode settings automatically:
| Setting | Default |
| ------------------- | -------------------------------------- |
| Install command | Detected from the package manager |
| Build command | Package script or `react-router build` |
| Development command | Package script or `react-router dev` |
| Static assets | Detected from the framework build |
| Server output | Detected from the deployment preset |
| Node.js version | Project or platform default |
For React Router 8, select a Node.js version compatible with its required baseline.
For monorepos, set the project root to the directory containing:
* The application’s `package.json`
* `react-router.config.ts`
* The Vite configuration
* The application routes
Local development [#local-development]
Continue using React Router’s normal development server:
```bash
npm run dev
```
The framework dev server provides routing, loaders, actions, server rendering, middleware, and hot module replacement.
Use Easel preview deployments to validate platform-specific behavior, including:
* The production server bundle
* Route-aware function packaging
* CDN caching
* Streaming through the production network
* Environment variables
* Function limits (including duration)
* WAF and security rules
A preview deployment follows the same build and deployment path as production and receives an immutable URL.
Upgrading from React Router 7 to 8 [#upgrading-from-react-router-7-to-8]
React Router 8 is designed as a non-breaking application API upgrade for projects that adopted the v8 future behavior in React Router 7.
Before upgrading:
1. Upgrade the application to the latest React Router 7 release
2. Enable supported `future.v8_*` flags
3. Resolve deprecations and behavior changes
4. Upgrade Node.js to at least 22.22.0
5. Upgrade React to at least 19.2.7
6. Upgrade Vite to version 7 or newer
7. Confirm the project is ESM-compatible
8. Upgrade the React Router packages together
9. Remove obsolete `future.v8_*` flags
10. Create an Easel preview deployment and test dynamic routes
React Router 8 makes the v8 middleware, request-passthrough, Vite environment, and related future behavior the default.
A typical package upgrade is:
```bash
npm install react-router@^8 \
@react-router/dev@^8
```
Upgrade any React Router adapters or deployment presets to versions that explicitly support React Router 8.
Known limitations [#known-limitations]
WebSockets [#websockets]
React Router routes deployed to Easel Functions cannot accept long-lived WebSocket connections.
Use an external WebSocket provider or a dedicated persistent service for bidirectional connections.
Streaming HTTP responses and Server-Sent Events are separate protocols and may be used within the function’s execution limits.
Local filesystem [#local-filesystem]
The function filesystem is ephemeral. Files written during one invocation are not guaranteed to exist during a later invocation or on another function instance.
Use object storage, a database, or another durable service for persistent data.
Long-running work [#long-running-work]
Loaders, actions, and middleware run within the function’s maximum duration.
Do not rely on untracked work continuing after a response is returned. Use a durable queue or background-job system for work that requires retries, may exceed the function limit, or must survive instance termination.
Custom Node.js servers [#custom-nodejs-servers]
Easel deploys the Web API-compatible React Router request handler generated by the framework integration. An application that requires ownership of a persistent HTTP server, raw TCP sockets, or process-level connection handling may require a dedicated service rather than Easel Functions.
Troubleshooting [#troubleshooting]
The build cannot import React Router 8 [#the-build-cannot-import-react-router-8]
Confirm that the project uses:
* Node.js 22.22.0 or newer
* React 19.2.7 or newer
* Vite 7 or newer
* ESM-compatible configuration
React Router 8 does not support older runtime baselines.
Middleware does not run in React Router 7 [#middleware-does-not-run-in-react-router-7]
Confirm that the installed React Router 7 release supports middleware and that `future.v8_middleware` is enabled.
Also remember that a client-side navigation with no server loader or action may not make a server request. Server middleware only runs when the navigation reaches the server.
A loader runs locally but not in production [#a-loader-runs-locally-but-not-in-production]
Confirm that SSR has not been disabled with:
```ts
ssr: false
```
SPA mode does not deploy server loaders or actions.
A route returns stale content [#a-route-returns-stale-content]
Inspect the route’s `Cache-Control` header. Do not apply shared CDN caching to authenticated or personalized responses unless the cache key safely distinguishes every response variant.
A cookie is not being set [#a-cookie-is-not-being-set]
Confirm that:
* The response includes `Set-Cookie`
* The cookie’s domain and path match the request
* `secure` cookies are tested over HTTPS
* The cookie does not exceed browser size limits
* An ancestor middleware does not replace the response headers
Deep links return a 404 in SPA mode [#deep-links-return-a-404-in-spa-mode]
Confirm that the application is built with React Router’s SPA mode rather than as an unrelated static Vite output. The framework deployment output includes the routing fallback Easel needs for application paths.
The application works on React Router 7 but fails after upgrading [#the-application-works-on-react-router-7-but-fails-after-upgrading]
Check the React Router 8 runtime baselines first. Then remove obsolete future flags and verify that deployment adapters and Vite plugins support v8.
Run the upgrade through a preview deployment before promoting it to production.
Compatibility policy [#compatibility-policy]
Easel tests its React Router integration with representative Framework Mode applications covering:
* React Router 7 and 8
* Server rendering
* Client navigations
* Loaders and actions
* Streaming
* Middleware
* Request context
* Resource routes
* Static prerendering
* SPA mode
* Sessions and cookies
* Response caching
* Route error boundaries
Stable releases may work beyond the versions listed at the top of this page, but those versions are the most recently verified baselines.
For a newly released React Router version, create a preview deployment before upgrading the production application.
Next steps [#next-steps]
Shared getCache() across isolates
Cache headers and edge behavior
Static Vite and SPA fallbacks
# SvelteKit on Easel
At a glance [#at-a-glance]
| | |
| ----------------------------- | ------------------------------------------------- |
| **Support level** | Production-ready |
| **Rendering** | Static, SSR, streaming, and client-side rendering |
| **Server runtime** | Node.js |
| **Required adapter** | `@sveltejs/adapter-vercel` |
| **Automatic detection** | Yes |
| **Most recently tested with** | SvelteKit 2.70.x |
Deploy a SvelteKit application [#deploy-a-sveltekit-application]
Install the [Vercel adapter](https://svelte.dev/docs/kit/adapter-vercel):
```bash
npm install -D @sveltejs/adapter-vercel
```
Then configure it in `svelte.config.js`:
```js title="svelte.config.js"
import adapter from "@sveltejs/adapter-vercel";
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
/** @type {import("@sveltejs/kit").Config} */
const config = {
preprocess: vitePreprocess(),
kit: {
adapter: adapter(),
},
};
export default config;
```
Deploy the project by connecting its Git repository to Easel or using the CLI:
```bash
easel deploy
```
Easel detects SvelteKit, installs the project’s dependencies, runs the production build, and deploys the output generated by the adapter.
The default build command is:
```bash
vite build
```
You can override the install command, build command, root directory, Node.js version, and environment variables in the project settings.
Why run SvelteKit on Easel? [#why-run-sveltekit-on-easel]
Easel provides a production SvelteKit deployment path using the framework’s standard adapter system.
A SvelteKit deployment includes:
* Prerendered pages and static assets served through the Easel CDN
* Regional functions for server-rendered pages and server-side code
* Streaming responses from server load functions and endpoints
* Support for form actions, hooks, and API routes
* Preview deployments for every branch and pull request
* Built-in logs, metrics, traces, WAF, and attack protection
* Vercel-compatible build output without requiring a Vercel deployment
You can inspect function execution, request routing, deployment output, and resource usage from the Easel dashboard.
Why is the Vercel adapter required? [#why-is-the-vercel-adapter-required]
SvelteKit uses adapters to convert a framework build into output that a hosting platform can deploy.
`@sveltejs/adapter-vercel` produces a Build Output API-compatible deployment containing:
* Client assets
* Prerendered pages
* Server-side application code
* Route and function configuration
* Redirect and routing metadata
Easel consumes this output directly. Using the adapter does not deploy the application to Vercel or require a Vercel account.
Do not use `adapter-auto` for production Easel deployments. Automatic adapter selection can change based on the detected build environment and does not provide an explicit, reproducible deployment contract.
What Easel deploys [#what-easel-deploys]
Easel maps the output generated by the SvelteKit adapter to the appropriate platform resources.
| SvelteKit output | Easel resource |
| ---------------------------- | ------------------------- |
| Files in `static` | CDN assets |
| Client JavaScript and CSS | CDN assets |
| Prerendered pages | CDN assets |
| Server-rendered pages | Easel Functions |
| Server `load` functions | Easel Functions |
| Form actions | Easel Functions |
| `+server` endpoints | Easel Functions |
| Server hooks | SvelteKit server function |
| Redirects and route metadata | Easel request routing |
Prerendered routes are excluded from the dynamic server manifest where possible, reducing the amount of server code required to handle requests.
Routes that require request-time data remain part of the server application and execute in Easel Functions.
Function topology [#function-topology]
By default, the adapter can package the server-rendered portion of the SvelteKit application into a shared function.
This allows layouts, pages, endpoints, hooks, and application state to share a server bundle while SvelteKit continues to route requests internally.
The adapter also supports splitting routes into separate functions. Easel support for adapter-level and route-level function splitting depends on the generated Build Output API configuration.
Use route splitting only when it provides a concrete benefit, such as:
* Isolating a resource-intensive endpoint
* Assigning different execution settings to a route
* Reducing the deployment size of frequently invoked routes
* Preventing one route’s dependencies from affecting unrelated routes
Splitting every route can increase build output, deployment complexity, and the number of independently initialized function bundles.
Supported features [#supported-features]
| Feature | Support | Notes |
| ----------------------------- | ------------------------- | --------------------------------------------------------------------------------- |
| Server-side rendering | Supported | Dynamic routes execute in Easel Functions |
| Prerendering | Supported | Generated files are deployed to the CDN |
| Client-side rendering | Supported | Controlled through SvelteKit page options |
| Streaming server loads | Supported | Promises returned from server load functions can stream as they resolve |
| Streaming endpoints | Supported | Standard `ReadableStream` responses are forwarded without full-response buffering |
| Universal load functions | Supported | Run according to SvelteKit’s normal server and browser lifecycle |
| Server load functions | Supported | Execute in the SvelteKit server function |
| Form actions | Supported | Includes progressive enhancement with `use:enhance` |
| API endpoints | Supported | `+server` handlers execute in Easel Functions |
| Server hooks | Supported | Includes `handle`, `handleFetch`, and `handleError` |
| Universal hooks | Supported | Included in the generated application bundle |
| Cookies and sessions | Supported | Standard SvelteKit cookie APIs are available |
| Redirects and errors | Supported | Standard SvelteKit response behavior is preserved |
| Route parameters | Supported | Includes optional, rest, and matched parameters |
| Route groups | Supported | Groups remain an application-level routing concern |
| Shallow routing | Supported | Client-side framework behavior |
| Service workers | Supported | Generated service-worker assets are deployed statically |
| Private environment variables | Supported | Available only to server-side code |
| Public environment variables | Supported | Exposed according to SvelteKit’s public-prefix rules |
| Dynamic environment variables | Supported | Resolved from the function environment at runtime |
| Static environment variables | Supported | Inlined during the production build |
| Server instrumentation | Supported | Included when emitted by the adapter |
| Base paths | Supported | Configure through `kit.paths.base` |
| Trailing-slash behavior | Supported | Controlled by SvelteKit route options |
| WebSockets | Not supported | Function routes use HTTP request-response semantics |
| Persistent local filesystem | Not supported | Function filesystems are ephemeral |
| Scheduled tasks | Not provided by SvelteKit | Use Easel scheduled functions or an external scheduler |
Rendering [#rendering]
SvelteKit lets an application combine static, server-rendered, and client-rendered routes.
Rendering behavior can be configured in:
* `+page.js`
* `+page.server.js`
* `+layout.js`
* `+layout.server.js`
* `+server.js`
Settings exported from a layout apply to its descendant routes unless overridden.
Server-side rendering [#server-side-rendering]
Pages are server-rendered by default.
A server load function can read private environment variables, access a database, inspect cookies, and return data to the page:
```ts title="src/routes/account/+page.server.ts"
import type { PageServerLoad } from "./$types";
export const load: PageServerLoad = async ({ locals }) => {
return {
user: locals.user,
};
};
```
The corresponding page receives the data:
```svelte title="src/routes/account/+page.svelte"
Welcome, {data.user.name}
```
The load function and page render execute in an Easel Function. The rendered HTML is returned to the browser and hydrated according to the application’s SvelteKit configuration.
Prerendering [#prerendering]
Routes that do not require request-time data can be generated during the build:
```ts title="src/routes/about/+page.ts"
export const prerender = true;
```
Prerendered pages are deployed as static files and served through the Easel CDN without invoking a function.
You can enable prerendering for a group of routes from a layout:
```ts title="src/routes/(marketing)/+layout.ts"
export const prerender = true;
```
Child routes can override the inherited value:
```ts title="src/routes/(marketing)/pricing/+page.server.ts"
export const prerender = false;
```
Use `prerender = "auto"` when some known route entries should be generated during the build while other parameter values remain available through server rendering:
```ts title="src/routes/blog/[slug]/+page.server.ts"
import type { EntryGenerator } from "./$types";
export const prerender = "auto";
export const entries: EntryGenerator = () => {
return [
{ slug: "introducing-easel" },
{ slug: "deploying-sveltekit" },
];
};
```
Routes fully removed from the dynamic manifest can reduce the size of the application’s server bundle.
Client-side rendering [#client-side-rendering]
Disable server rendering for a route when it must run entirely in the browser:
```ts title="src/routes/dashboard/+page.ts"
export const ssr = false;
```
This produces a client-rendered application shell for that route. Browser requests for the route still require the appropriate fallback and routing metadata generated by the adapter.
You can also disable hydration for content that should remain static HTML:
```ts title="src/routes/legal/+page.ts"
export const csr = false;
```
Use these options deliberately. Prefer server rendering when you want better initial HTML, progressive enhancement, and resilience if client-side JavaScript fails to load.
Streaming [#streaming]
SvelteKit server load functions can return promises that resolve after the initial page data.
```ts title="src/routes/products/[id]/+page.server.ts"
import type { PageServerLoad } from "./$types";
export const load: PageServerLoad = async ({ params, fetch }) => {
const product = await loadProduct(params.id);
return {
product,
reviews: fetch(`/api/products/${params.id}/reviews`).then((response) =>
response.json(),
),
};
};
```
The page can render the required product information immediately and update when the reviews resolve:
```svelte title="src/routes/products/[id]/+page.svelte"
{data.product.name}
{#await data.reviews}
Loading reviews…
{:then reviews}
{#each reviews as review}
- {review.body}
{/each}
{:catch}
Reviews could not be loaded.
{/await}
```
Easel forwards the response as SvelteKit produces it rather than waiting for every streamed promise to settle.
Once a response has started streaming, its status and headers can no longer be changed. Do not attempt to redirect or call `setHeaders` from inside a promise that resolves after streaming begins.
Streaming load data requires browser JavaScript. Without JavaScript, the browser waits for the complete server-rendered response.
Form actions [#form-actions]
SvelteKit form actions execute in the application’s server function.
```ts title="src/routes/contact/+page.server.ts"
import { fail } from "@sveltejs/kit";
import type { Actions } from "./$types";
export const actions = {
default: async ({ request }) => {
const data = await request.formData();
const email = data.get("email");
if (typeof email !== "string" || !email.includes("@")) {
return fail(400, {
email,
invalid: true,
});
}
await saveContactRequest({
email,
});
return {
success: true,
};
},
} satisfies Actions;
```
Use a standard HTML form for progressive enhancement:
```svelte title="src/routes/contact/+page.svelte"
{#if form?.invalid}
Enter a valid email address.
{/if}
{#if form?.success}
Your request was received.
{/if}
```
The form remains functional without browser JavaScript. With `use:enhance`, SvelteKit submits the request without a full-page reload and updates the action data in place.
API endpoints [#api-endpoints]
Create HTTP endpoints with `+server` files:
```ts title="src/routes/api/health/+server.ts"
import { json } from "@sveltejs/kit";
import type { RequestHandler } from "./$types";
export const GET: RequestHandler = () => {
return json({
ok: true,
timestamp: new Date().toISOString(),
});
};
```
Endpoint handlers can return any standard `Response`, including JSON, redirects, files, Server-Sent Events, and streaming bodies.
A streaming endpoint can return a `ReadableStream`:
```ts title="src/routes/api/events/+server.ts"
import type { RequestHandler } from "./$types";
const encoder = new TextEncoder();
export const GET: RequestHandler = () => {
const stream = new ReadableStream({
start(controller) {
controller.enqueue(
encoder.encode('data: {"status":"connected"}\n\n'),
);
controller.close();
},
});
return new Response(stream, {
headers: {
"content-type": "text/event-stream",
"cache-control": "no-cache",
},
});
};
```
Long-lived responses remain subject to the route’s function execution limit. Use a persistent service for indefinite connections.
Hooks [#hooks]
Server hooks run inside the SvelteKit server function.
Use `handle` to authenticate requests, populate `event.locals`, modify responses, or bypass normal route handling:
```ts title="src/hooks.server.ts"
import type { Handle } from "@sveltejs/kit";
export const handle: Handle = async ({ event, resolve }) => {
const session = event.cookies.get("session");
event.locals.user = session
? await findUserBySession(session)
: null;
const response = await resolve(event);
response.headers.set("x-application", "easel-sveltekit");
return response;
};
```
The populated value is available to server load functions, form actions, and endpoints:
```ts title="src/routes/account/+page.server.ts"
import { redirect } from "@sveltejs/kit";
import type { PageServerLoad } from "./$types";
export const load: PageServerLoad = ({ locals }) => {
if (!locals.user) {
redirect(303, "/login");
}
return {
user: locals.user,
};
};
```
Use `handleFetch` when you need to modify server-side requests made through SvelteKit’s enhanced `fetch` implementation.
Cookies and sessions [#cookies-and-sessions]
SvelteKit’s `cookies` API is available in server load functions, actions, endpoints, and hooks:
```ts title="src/routes/login/+page.server.ts"
import { redirect } from "@sveltejs/kit";
import type { Actions } from "./$types";
export const actions = {
default: async ({ request, cookies }) => {
const data = await request.formData();
const session = await createSession(data);
cookies.set("session", session.id, {
path: "/",
httpOnly: true,
sameSite: "lax",
secure: true,
maxAge: 60 * 60 * 24 * 30,
});
redirect(303, "/account");
},
} satisfies Actions;
```
Cookies are sent through Easel’s request pipeline to the application function and returned through standard `Set-Cookie` response headers.
Store durable session state in a database or shared session store rather than in function memory.
Cache control [#cache-control]
Set cache headers from server load functions with `setHeaders`:
```ts title="src/routes/blog/[slug]/+page.server.ts"
import type { PageServerLoad } from "./$types";
export const load: PageServerLoad = async ({
params,
setHeaders,
}) => {
const post = await loadPost(params.slug);
setHeaders({
"cache-control":
"public, max-age=0, s-maxage=300, stale-while-revalidate=86400",
});
return {
post,
};
};
```
For endpoint responses, set headers directly:
```ts title="src/routes/api/catalog/+server.ts"
import { json } from "@sveltejs/kit";
import type { RequestHandler } from "./$types";
export const GET: RequestHandler = async () => {
const products = await loadProducts();
return json(products, {
headers: {
"cache-control":
"public, max-age=0, s-maxage=300, stale-while-revalidate=3600",
},
});
};
```
Easel’s CDN interprets supported HTTP cache directives for eligible responses. See [Cache responses at the edge](/docs/cdn/caching) and [Invalidate and revalidate cached content](/docs/cdn/revalidation).
Do not publicly cache responses containing user-specific data, authentication state, private cookies, or personalized content.
Environment variables [#environment-variables]
SvelteKit distinguishes private from public variables and static from dynamic variables.
Private variables [#private-variables]
Private variables are available only to server-side code:
```ts title="src/lib/server/database.ts"
import { DATABASE_URL } from "$env/static/private";
export const database = connect(DATABASE_URL);
```
SvelteKit prevents private environment modules from being imported into browser code.
Public variables [#public-variables]
Public variables use the configured public prefix, which is `PUBLIC_` by default:
```ts
import { PUBLIC_API_ORIGIN } from "$env/static/public";
```
Public values can be included in browser bundles and must not contain secrets.
Static variables [#static-variables]
Static variables are replaced during the build:
```ts
import { FEATURE_FLAG } from "$env/static/private";
```
Changing a static variable requires a new deployment.
Dynamic variables [#dynamic-variables]
Dynamic variables are read from the function environment when the application handles a request:
```ts
import { env } from "$env/dynamic/private";
export function loadDatabaseConfig() {
return {
url: env.DATABASE_URL,
};
}
```
Dynamic access is useful when a value should remain outside the generated server bundle or can vary without being statically imported.
Explicit environment variables [#explicit-environment-variables]
Recent SvelteKit 2 releases allow applications to opt into the explicit environment-variable system planned for SvelteKit 3.
When enabled, variables are declared in `src/env.ts` and imported through `$app/env/private` or `$app/env/public`.
Easel supplies the underlying build-time and runtime environment variables. The SvelteKit version and application configuration determine which framework modules expose them.
Adapter configuration [#adapter-configuration]
The Vercel adapter accepts options designed for Vercel’s infrastructure. Not every provider-specific option changes an Easel deployment.
The adapter’s primary purpose on Easel is to generate:
* Server function output
* Static and prerendered assets
* Routing configuration
* Build Output API metadata
Easel project settings remain authoritative for platform resources such as:
* Function memory
* CPU allocation
* Maximum execution duration (framework `maxDuration` when emitted)
* Environment variables
* Scaling limits
Do not rely on adapter memory, duration, or region settings unless the corresponding option is explicitly documented as supported by Easel. Functions run in US East.
Image optimization [#image-optimization]
Static images imported or referenced by the application deploy normally as client assets.
SvelteKit itself does not prescribe a single runtime image-transformation service. Image behavior depends on the component, preprocessor, or image package used by the application.
Build-time image processing works when it produces ordinary static assets during `vite build`.
For runtime transformation, use Easel’s image service or another documented image provider. Verify framework-specific image plugins in a preview deployment before relying on them in production.
Base paths [#base-paths]
Configure an application mounted below the domain root through `kit.paths.base`:
```js title="svelte.config.js"
import adapter from "@sveltejs/adapter-vercel";
export default {
kit: {
adapter: adapter(),
paths: {
base: "/app",
},
},
};
```
Use SvelteKit’s path helpers when generating links and asset URLs so the configured base path is preserved.
Trailing slashes [#trailing-slashes]
Configure trailing-slash behavior from a layout or page:
```ts title="src/routes/+layout.ts"
export const trailingSlash = "always";
```
Supported values are:
* `"never"`
* `"always"`
* `"ignore"`
The setting also affects paths generated during prerendering.
Service workers [#service-workers]
SvelteKit service workers are built as static application assets and deployed through the CDN.
Create one at `src/service-worker.js` or `src/service-worker.ts`:
```ts title="src/service-worker.ts"
import { build, files, version } from "$service-worker";
const cacheName = `cache-${version}`;
const assets = [...build, ...files];
self.addEventListener("install", (event) => {
event.waitUntil(
caches.open(cacheName).then((cache) => cache.addAll(assets)),
);
});
```
A service worker executes in the visitor’s browser, not inside an Easel Function. Ensure caching rules account for immutable deployment assets and application-version changes.
Project configuration [#project-configuration]
Easel detects conventional SvelteKit project settings automatically:
| Setting | Default |
| ------------------- | --------------------------------- |
| Install command | Detected from the package manager |
| Build command | Package script or `vite build` |
| Output directory | Read from the adapter output |
| Development command | Package script or `vite dev` |
| Node.js version | Project or platform default |
For monorepos, set the project root to the directory containing the SvelteKit application’s `package.json` and `svelte.config.js`.
The project must include the production adapter in its dependencies and configuration.
Local development [#local-development]
Continue using SvelteKit’s normal development server:
```bash
npm run dev
```
The Vite development server provides SvelteKit routing, server rendering, load functions, actions, hooks, and endpoints locally.
Use an Easel preview deployment to validate behavior that depends on the production platform:
* Production adapter output
* Function packaging
* Streaming through the request pipeline
* CDN caching
* Runtime environment variables
* Function duration and resource limits
* WAF and security rules
* Platform resource limits
Every preview deployment uses the production build path and receives its own immutable URL.
Known limitations [#known-limitations]
WebSockets [#websockets]
SvelteKit routes deployed to Easel Functions cannot accept long-lived WebSocket connections.
Use an external WebSocket provider or a dedicated persistent service for bidirectional communication.
HTTP streaming and Server-Sent Events are separate from WebSockets, but remain subject to function execution limits.
Persistent local filesystem [#persistent-local-filesystem]
The function filesystem is ephemeral.
Files written during an invocation are not guaranteed to exist in a later request or on another function instance. Use object storage, a database, or another durable service for persistent data.
Durable background work [#durable-background-work]
Do not start untracked asynchronous work after returning a response.
Function execution may end once the request lifecycle is complete. Use a queue, scheduled function, or durable background-work system for tasks that require retries or must survive function termination.
Adapter-specific infrastructure settings [#adapter-specific-infrastructure-settings]
The Vercel adapter contains options tied specifically to Vercel’s function products.
Easel consumes the portable deployment output, but does not necessarily reproduce every Vercel-specific control. Configure Easel infrastructure from the Easel project settings unless a particular adapter option is documented as supported.
Runtime image plugins [#runtime-image-plugins]
Build-time image output works as static assets. Runtime image packages may depend on provider-specific APIs and should be tested independently.
Troubleshooting [#troubleshooting]
Easel does not detect the server application [#easel-does-not-detect-the-server-application]
Confirm that `@sveltejs/adapter-vercel` is installed and selected in `svelte.config.js`.
Do not rely on `adapter-auto` for the production deployment.
The deployment contains only static files [#the-deployment-contains-only-static-files]
Check whether `prerender = true` is exported from the root layout or inherited by the affected routes.
Routes that are fully prerendered do not remain in the dynamic server manifest.
A route fails during prerendering [#a-route-fails-during-prerendering]
A prerendered route cannot depend on request-specific cookies, headers, authentication state, or runtime-only data.
Set `prerender = false` for the route or move the request-dependent work to a dynamically rendered route.
A dynamic route is missing from the prerendered output [#a-dynamic-route-is-missing-from-the-prerendered-output]
SvelteKit must know which parameter values to generate.
Export an `entries` function or make the route discoverable through links crawled from another prerendered page.
An environment variable is undefined [#an-environment-variable-is-undefined]
Confirm that the variable exists in the current Easel environment.
Also verify that the application uses the correct SvelteKit module:
* Static or dynamic
* Private or public
* Legacy `$env` modules or the explicit `$app/env` system
Static variables require a new deployment after their values change.
A public variable is unavailable in browser code [#a-public-variable-is-unavailable-in-browser-code]
By default, public environment variables must use the `PUBLIC_` prefix.
Variables without the public prefix remain server-only.
A streamed value never appears early [#a-streamed-value-never-appears-early]
Ensure the promise is returned from a server load function rather than awaited before the function returns.
Also confirm that the surrounding application code and any upstream services do not buffer the complete response.
Headers fail inside streamed data [#headers-fail-inside-streamed-data]
Headers and status codes cannot change after the response starts.
Set headers before returning the initial load result, and do not redirect from inside a streamed promise.
Cookies are not being set [#cookies-are-not-being-set]
Confirm that the cookie includes an appropriate `path`, and verify the `secure` and `sameSite` settings for the deployment environment.
Code works locally but fails after deployment [#code-works-locally-but-fails-after-deployment]
Inspect the production build logs and function logs from a preview deployment.
Common causes include:
* Missing runtime environment variables
* Native packages built for the wrong environment
* Case-sensitive import paths
* Provider-specific adapter options
* Access to persistent local files
* Code that uses browser APIs during server rendering
Compatibility policy [#compatibility-policy]
Easel tests its SvelteKit integration against representative applications covering:
* Server-side rendering
* Prerendering
* Server and universal load functions
* Streaming promises
* Form actions
* Hooks
* API endpoints
* Cookies and sessions
* Static and dynamic environment variables
* Base paths
* Redirects
* Error handling
Stable SvelteKit releases may work beyond the version listed at the top of this page, but the listed version is the most recently verified baseline.
For a newly released SvelteKit version, an experimental framework feature, or a provider-specific adapter option, create a preview deployment before upgrading the production application.
# TanStack Start on Easel
At a glance [#at-a-glance]
| | |
| ----------------------------- | --------------------------------------------------- |
| **Support level** | Production-ready |
| **Rendering** | Static, SSR, streaming, selective SSR, and SPA mode |
| **Server runtime** | Node.js |
| **Deployment integration** | Nitro |
| **Adapter required** | Yes |
| **Automatic detection** | Yes |
| **Most recently tested with** | TanStack Start RC |
Deploy a TanStack Start application [#deploy-a-tanstack-start-application]
TanStack Start applications use Nitro to produce the server entry and static assets Easel deploys.
Install Nitro:
```bash
npm install nitro
```
Add the Nitro Vite plugin after `tanstackStart()` and before the React plugin:
```ts title="vite.config.ts"
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
import { nitro } from "nitro/vite";
export default defineConfig({
plugins: [
tanstackStart(),
nitro(),
react(),
],
});
```
Do not manually configure a Nitro deployment preset for Easel. During the platform build, Easel selects the hosting output it expects.
Connect the project’s Git repository to Easel or deploy it with the CLI:
```bash
easel deploy
```
Easel detects TanStack Start, installs dependencies, runs the production build, and deploys the generated client and server output.
The default build command is:
```bash
vite build
```
You can override the install command, build command, root directory, Node.js version, and environment variables in your project settings.
Why run TanStack Start on Easel? [#why-run-tanstack-start-on-easel]
TanStack Start keeps routing, data loading, and server boundaries inside the application while allowing the deployment target to remain portable.
Easel preserves that model. Your application uses standard TanStack Start and Nitro integrations rather than an Easel-specific framework fork.
A TanStack Start deployment includes:
* Immutable client assets served through the Easel CDN
* Regional functions for server rendering and server-side code
* Streaming responses from routes and server functions
* Type-safe server functions callable from loaders and components
* Server routes for external HTTP endpoints
* Middleware for authentication, context, logging, and request policy
* Preview deployments for every branch and pull request
* Built-in logs, metrics, traces, WAF, and attack protection
You can inspect function execution, request routing, cache behavior, and resource usage from the Easel dashboard.
What Easel deploys [#what-easel-deploys]
The Nitro build produces a client application and a server entry that implements TanStack Start’s request handling.
Easel maps that output to platform resources:
| Application output | Easel resource |
| ---------------------------------------- | ---------------------------- |
| JavaScript, CSS, fonts, and public files | CDN assets |
| Prerendered pages | CDN assets |
| Server-rendered routes | Easel Functions |
| Route loaders requiring server execution | Easel Functions |
| Server functions | Application server function |
| Server routes | Function-backed HTTP routes |
| Start middleware | Application server function |
| Streaming responses | Function response stream |
| Application telemetry | Easel observability pipeline |
Static files are deployed immutably to the CDN. Requests requiring TanStack Start’s server runtime are forwarded to the generated server entry.
Server functions are part of the application’s server bundle. They are not deployed as individually configurable Easel Functions unless the build output explicitly separates them.
Supported features [#supported-features]
| Feature | Support | Notes |
| ------------------------------- | -------------------- | --------------------------------------------------------------------------- |
| File-based routing | Supported | Routes generated by TanStack Router are included in the application build |
| Full-document SSR | Supported | Routes render in Easel Functions |
| Streaming SSR | Supported | HTML is forwarded as the framework produces it |
| Client-side navigation | Supported | Client assets and route manifests are served through the CDN |
| Route loaders | Supported | Loaders run in the environment selected by the route |
| `beforeLoad` | Supported | Runs as part of TanStack Router’s route lifecycle |
| Server functions | Supported | Includes validated, type-safe calls from client and server code |
| Streaming server functions | Supported | Includes `ReadableStream` and async-generator responses |
| Server routes | Supported | Expose external HTTP endpoints from the Start application |
| Middleware | Supported | Includes request, function, and server-route middleware |
| Selective SSR | Supported | Routes can opt into full, data-only, or client-only rendering |
| SPA mode | Supported | The application server provides the required document fallback |
| Static prerendering | Supported with setup | Routes configured for prerendering are emitted as static output |
| Incremental Static Regeneration | Experimental | Depends on the framework and Nitro output used by the application |
| Redirects and headers | Supported | Return them through standard framework response APIs |
| Cookies and sessions | Supported | Standard request and response cookie behavior is preserved |
| Environment variables | Supported | Server variables remain outside the client bundle unless explicitly exposed |
| Request cancellation | Supported | Long-running server work can observe the request’s `AbortSignal` |
| Early Hints | Runtime-dependent | Verify behavior in a preview deployment |
| OpenTelemetry | Supported | Standard Node.js instrumentation can export through Easel |
| WebSockets | Not supported | Function requests use HTTP request-response semantics |
| Durable background jobs | Not supported | Use a dedicated queue or background-work service |
TanStack Start and `nitro/vite` are evolving rapidly. Experimental framework behavior should be validated in a preview deployment before it is promoted to production.
Rendering [#rendering]
TanStack Start allows each route to select how much work happens on the server.
Full SSR [#full-ssr]
Full SSR sends both the route’s data and rendered markup from the server.
```tsx title="src/routes/products.tsx"
import { createFileRoute } from "@tanstack/react-router";
export const Route = createFileRoute("/products")({
loader: async () => {
return getProducts();
},
component: ProductsPage,
});
function ProductsPage() {
const products = Route.useLoaderData();
return (
{products.map((product) => (
- {product.name}
))}
);
}
```
The initial request runs through the TanStack Start server entry in an Easel Function. The generated HTML can begin streaming while the route completes its work.
The browser hydrates the returned document and handles later navigations through TanStack Router.
Data-only SSR [#data-only-ssr]
A route can run its loader on the server without rendering its component markup there:
```tsx
export const Route = createFileRoute("/dashboard")({
ssr: "data-only",
loader: async () => {
return getDashboardData();
},
component: DashboardPage,
});
```
The server returns the route data required by the client, while the component itself renders in the browser.
Client-only rendering [#client-only-rendering]
Disable server rendering for a route when it depends entirely on browser APIs or should only render after hydration:
```tsx
export const Route = createFileRoute("/editor")({
ssr: false,
component: EditorPage,
});
```
The route remains part of the TanStack Start application, but its component does not render during the server response.
Streaming [#streaming]
Easel forwards response chunks as TanStack Start produces them rather than waiting for the entire document to finish rendering.
This allows the initial document shell and completed route regions to reach the browser while slower data is still resolving.
Streaming remains subject to the function’s maximum execution duration. A disconnected client can also cancel request-bound work when the application observes the request’s abort signal.
Server functions [#server-functions]
Server functions define server-only logic that can be imported and called from loaders, components, hooks, and other server functions.
```tsx title="src/data/products.functions.ts"
import { createServerFn } from "@tanstack/react-start";
import { z } from "zod";
const ProductInput = z.object({
id: z.string(),
});
export const getProduct = createServerFn({
method: "GET",
})
.inputValidator(ProductInput)
.handler(async ({ data }) => {
return db.product.findUnique({
where: {
id: data.id,
},
});
});
```
Call the function from application code:
```tsx
const product = await getProduct({
data: {
id: "product_123",
},
});
```
TanStack Start converts client-side calls into HTTP requests and dispatches them to the corresponding server implementation.
The server handler can access:
* Databases and private services
* Server-only environment variables
* Request headers and cookies
* Authentication context
* The request’s cancellation signal
* Node.js runtime APIs supported by Easel Functions
Server function identifiers and dispatch behavior are generated by TanStack Start during the production build.
Keep server-only code isolated [#keep-server-only-code-isolated]
Use `.server.ts` files for implementation details that must never enter a client bundle:
```ts title="src/data/products.server.ts"
import { db } from "~/db";
export async function findProduct(id: string) {
return db.product.findUnique({
where: {
id,
},
});
}
```
Import the server-only helper inside the server function handler:
```tsx title="src/data/products.functions.ts"
import { createServerFn } from "@tanstack/react-start";
export const getProduct = createServerFn({
method: "GET",
})
.inputValidator((id: string) => id)
.handler(async ({ data: id }) => {
const { findProduct } = await import("./products.server");
return findProduct(id);
});
```
TanStack Start’s build-time environment separation prevents server implementation code from being included in the browser bundle.
Streaming from server functions [#streaming-from-server-functions]
Server functions can return streaming data using a `ReadableStream` or async generator.
```tsx
import { createServerFn } from "@tanstack/react-start";
export const generateReport = createServerFn({
method: "POST",
}).handler(async function* () {
yield {
status: "starting",
};
for await (const section of buildReport()) {
yield {
status: "progress",
section,
};
}
yield {
status: "complete",
};
});
```
Easel keeps the HTTP response open and forwards chunks as the server function yields them.
The invocation remains active and billable until the stream closes, the client disconnects, or the function reaches its execution limit.
For durable work that must continue after a disconnect or survive function termination, submit the job to a queue and stream or poll its persisted state separately.
Server routes [#server-routes]
Use server routes for endpoints intended to be called outside the TanStack Start application.
```tsx title="src/routes/api/health.ts"
import { createFileRoute } from "@tanstack/react-router";
export const Route = createFileRoute("/api/health")({
server: {
handlers: {
GET: async () => {
return Response.json({
ok: true,
checkedAt: new Date().toISOString(),
});
},
},
},
});
```
Server routes can return:
* JSON responses
* HTML
* Redirects
* Custom headers and status codes
* `ReadableStream` responses
* Server-Sent Events
Server routes and server functions are both handled by the generated Start server entry, but they serve different purposes:
| Primitive | Intended use |
| --------------- | ------------------------------------------------------- |
| Server function | Type-safe calls made by your TanStack Start application |
| Server route | Public or externally called HTTP endpoint |
Use a server route for webhooks, public APIs, health checks, file responses, and integrations that do not call through the generated Start client.
Middleware [#middleware]
TanStack Start middleware can add shared request behavior without duplicating it across routes or server functions.
Common uses include:
* Authentication and authorization
* Request context
* Logging
* Rate-limit metadata
* Security policy
* Response headers
* Error handling
```tsx
import {
createMiddleware,
getRequestHeader,
} from "@tanstack/react-start";
export const authMiddleware = createMiddleware().server(
async ({ next }) => {
const authorization = getRequestHeader("authorization");
const user = await authenticate(authorization);
if (!user) {
throw new Response("Unauthorized", {
status: 401,
});
}
return next({
context: {
user,
},
});
},
);
```
This middleware runs inside the TanStack Start application function. It should not be confused with Easel’s CDN or WAF request pipeline.
Use Easel security rules for infrastructure-level filtering and TanStack Start middleware for application-level behavior.
Static prerendering [#static-prerendering]
TanStack Start can prerender selected routes during the production build.
Prerendered HTML and its associated client assets are deployed to the Easel CDN. Requests for those pages do not need to invoke the application function unless the route later requires dynamic behavior.
Use prerendering for content that can be generated without request-specific data, such as:
* Marketing pages
* Documentation
* Blog posts
* Public product pages
* Terms and policy pages
The precise configuration depends on the TanStack Start version used by the project. Easel deploys the static output generated by Start and Nitro rather than discovering routes independently.
When adding or changing prerender configuration, verify the generated routes in a preview deployment.
Caching [#caching]
TanStack Start does not impose one universal application-cache model. Caching behavior can come from:
* Browser cache headers
* Easel’s CDN
* Application-level caches
* Nitro caching utilities
* Database or external cache services
* Prerendered output
* Experimental ISR support
CDN caching [#cdn-caching]
Set standard cache headers on server-route responses:
```tsx
export const Route = createFileRoute("/api/catalog")({
server: {
handlers: {
GET: async () => {
const catalog = await getCatalog();
return Response.json(catalog, {
headers: {
"Cache-Control":
"public, s-maxage=300, stale-while-revalidate=60",
},
});
},
},
},
});
```
Shared-cache directives allow eligible responses to be cached by Easel’s CDN.
Do not publicly cache responses containing user-specific or authenticated data.
Server function caching [#server-function-caching]
Server functions may set response headers through TanStack Start’s server request utilities.
```tsx
import {
createServerFn,
setResponseHeaders,
} from "@tanstack/react-start";
export const getPublicCatalog = createServerFn({
method: "GET",
}).handler(async () => {
setResponseHeaders(
new Headers({
"Cache-Control":
"public, s-maxage=300, stale-while-revalidate=60",
}),
);
return getCatalog();
});
```
Server functions are frequently user-specific. Cache them publicly only when their output is safe to share across callers.
Nitro storage and caching [#nitro-storage-and-caching]
Nitro provides storage and caching abstractions, but their durability depends on the configured storage driver.
Do not rely on in-memory or local-filesystem storage to persist across Easel Function instances. Configure an external durable driver when cached data must be shared between instances or survive instance replacement.
Environment variables [#environment-variables]
Configure environment variables in the Easel dashboard or CLI.
Server-only variables can be accessed in server functions, server routes, middleware, and route loaders that execute on the server:
```ts
const databaseUrl = process.env.DATABASE_URL;
```
Only expose a value to browser code when it is intentionally public. Vite statically replaces client-visible variables during the build:
```ts
const apiOrigin = import.meta.env.VITE_PUBLIC_API_ORIGIN;
```
Any value available through `import.meta.env` in client code should be treated as public.
Changing a build-time client variable requires a new deployment. Use separate values for production, preview, and development environments when necessary.
OpenTelemetry [#opentelemetry]
TanStack Start applications running in Easel Functions can use standard Node.js OpenTelemetry instrumentation.
Instrument:
* Server-rendered requests
* Route loaders
* Server functions
* Server routes
* Database queries
* External API requests
* Application-defined operations
Easel can collect application spans alongside function metrics, request logs, and platform traces.
See [OpenTelemetry](/docs/observability/opentelemetry) for how Easel collects application spans into request Traces.
Project configuration [#project-configuration]
Easel detects conventional TanStack Start settings automatically:
| Setting | Default |
| ------------------- | --------------------------------- |
| Install command | Detected from the package manager |
| Build command | Package script or `vite build` |
| Development command | Package script or `vite dev` |
| Client output | Detected from the Nitro build |
| Server output | Detected from the Nitro build |
| Node.js version | Project or platform default |
For monorepos, set the project root to the directory containing the TanStack Start application’s `package.json` and `vite.config`.
Do not manually set a different Nitro preset or `NITRO_PRESET` for the Easel production build. Overriding the preset may produce a server shape that Easel cannot deploy.
Local development [#local-development]
Continue using TanStack Start’s normal Vite development server:
```bash
npm run dev
```
The Nitro plugin integrates the application server into the Vite development environment.
Local development is best for application logic, routes, loaders, server functions, and middleware. Use an Easel preview deployment to validate platform-specific behavior, including:
* Production bundling
* Function execution
* CDN caching
* Streaming through the production request path
* Environment variables
* Function duration and resource limits
* WAF and security rules
* Production observability
A preview deployment follows the same deployment path as production and receives its own immutable URL.
Known limitations [#known-limitations]
Nitro integration maturity [#nitro-integration-maturity]
The `nitro/vite` integration uses Vite’s environment APIs and remains under active development.
TanStack Start, Nitro, or Vite updates can change the generated server output. Review framework release notes and create a preview deployment before upgrading production dependencies.
Pin framework and Nitro versions when deployment stability is more important than receiving updates immediately.
WebSockets [#websockets]
TanStack Start applications deployed to Easel Functions cannot accept long-lived WebSocket connections.
Use an external WebSocket provider or a persistent service for bidirectional connections.
Streaming HTTP responses and Server-Sent Events are separate from WebSockets and can operate within the function’s execution limits.
Local filesystem [#local-filesystem]
Function filesystems are ephemeral. Files written during one invocation are not guaranteed to exist in later invocations or on another instance.
Use object storage, a database, or another durable service for persistent data.
In-memory state [#in-memory-state]
Global variables and in-memory caches may survive across requests handled by the same warm instance, but they are not shared across instances and can disappear at any time.
Do not use process memory as the source of truth for sessions, locks, queues, rate limits, or application data.
Background work [#background-work]
Work started during a request is not guaranteed to continue after the function invocation ends.
Use a durable queue or background-work service for jobs that require retries, exceed request duration limits, or must survive process termination.
Incremental Static Regeneration [#incremental-static-regeneration]
TanStack Start and Nitro’s incremental regeneration capabilities are evolving. Treat ISR behavior as experimental unless the specific route configuration has been verified against the framework and Nitro versions used by the project.
For predictable static output, use build-time prerendering. For dynamic responses, use explicit cache headers or an application cache.
Troubleshooting [#troubleshooting]
The build does not produce a server entry [#the-build-does-not-produce-a-server-entry]
Confirm that Nitro is installed:
```bash
npm install nitro
```
Then confirm that `nitro()` appears in `vite.config.ts` after `tanstackStart()`:
```ts
plugins: [
tanstackStart(),
nitro(),
react(),
]
```
A standard TanStack Start client build without a compatible server output does not contain the production entry Easel expects.
Easel cannot deploy the generated output [#easel-cannot-deploy-the-generated-output]
Remove any manually configured Nitro preset or `NITRO_PRESET` environment variable.
Easel selects its supported hosting output during the platform build. A manually selected Node, Bun, or provider-specific preset may produce a different directory structure or server interface.
A server function is unavailable [#a-server-function-is-unavailable]
Confirm that the function is created with `createServerFn` and exported from a module included in the production build.
Keep server-only implementation details in `.server.ts` modules and import them from inside the server handler.
Server-only code appears in the client build [#server-only-code-appears-in-the-client-build]
Move private implementation code into a `.server.ts` file. Do not export secrets or database clients from modules that can run in the browser.
Also verify that environment-variable names intended for the server are not exposed through Vite’s public client-variable prefix.
A route works locally but fails after deployment [#a-route-works-locally-but-fails-after-deployment]
Create a preview deployment and inspect the build and function logs.
Common causes include:
* Missing production environment variables
* Case-sensitive file paths
* Native dependencies unavailable for the selected runtime
* Reliance on the local filesystem
* A manually selected Nitro preset
* Code that assumes one long-lived server process
* Browser-only APIs executing during SSR
A stream is interrupted [#a-stream-is-interrupted]
Confirm that the application closes the stream normally and handles client cancellation.
Long-running streams remain subject to the function’s maximum duration. Use a durable job model when the underlying operation may outlive the request.
Cached data is shared between users [#cached-data-is-shared-between-users]
Do not mark authenticated or personalized responses as public.
Use `private` or `no-store` for user-specific responses, and include appropriate `Vary` headers where cache behavior depends on request headers.
Compatibility policy [#compatibility-policy]
Easel tests its TanStack Start integration against representative applications covering:
* Full-document SSR
* Streaming
* Route loaders
* Server functions
* Streaming server functions
* Server routes
* Middleware
* Selective SSR
* SPA mode
* Static assets
* Static prerendering
* Environment variables
* Production Nitro output
Stable framework releases may work beyond the version listed at the top of this page, but the listed version is the most recently verified baseline.
Because TanStack Start and `nitro/vite` are under active development, deploy dependency upgrades to a preview environment before promoting them to production.
# Vite on Easel
Easel supports React, Vue, Preact, Solid, Svelte, and other client-side applications built with Vite. Frameworks that use Vite for server rendering, such as SvelteKit, Nuxt, React Router, and TanStack Start, should use their [dedicated framework guide](/docs/framework-guides).
At a glance [#at-a-glance]
| | |
| ----------------------------- | ------------------------------- |
| **Support level** | Production-ready |
| **Rendering** | Static and client-side rendered |
| **Server runtime** | None |
| **Adapter required** | No |
| **Automatic detection** | Yes |
| **Default output directory** | `dist` |
| **Most recently tested with** | Vite 7.x |
Deploy a Vite application [#deploy-a-vite-application]
Easel detects Vite projects automatically.
[Create a project](/docs/getting-started) and connect the project’s Git repository, or [deploy with the CLI](/docs/cli/deploy):
```bash
easel deploy
```
Easel detects the package manager, installs dependencies, runs the production build, and deploys the generated files to the Easel CDN.
The default build command is:
```bash
vite build
```
Most projects define this through a package script:
```json
{
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
}
}
```
The default output directory is:
```text
dist
```
You can override the install command, build command, root directory, output directory, Node.js version, and environment variables in your project settings.
Why run Vite on Easel? [#why-run-vite-on-easel]
Vite applications deploy to Easel as immutable static assets distributed through the global CDN.
A Vite deployment includes:
* Automatic framework and build-command detection
* Immutable JavaScript, CSS, image, font, and media assets
* Global CDN delivery
* Configurable redirects, rewrites, and response headers
* Single-page application routing
* Preview deployments for every branch and pull request
* Built-in traffic analytics, logs, WAF, and attack protection
* Atomic deployments with instant rollback
Static Vite applications do not invoke Easel Functions during page requests. This keeps request handling fast and avoids function compute charges.
What Easel deploys [#what-easel-deploys]
Vite transforms your source code into browser-ready static files. Easel uploads those files to its CDN and serves them directly.
| Vite output | Easel resource |
| ------------------------- | --------------------------- |
| `index.html` | CDN asset |
| JavaScript bundles | Immutable CDN assets |
| CSS bundles | Immutable CDN assets |
| Imported images and fonts | Immutable CDN assets |
| Files from `public` | CDN assets |
| Source maps | CDN assets when included |
| Client-side routes | CDN rewrite to `index.html` |
Assets with content hashes in their filenames can be cached for long periods because a changed asset receives a new URL.
HTML files use shorter cache lifetimes so new deployments can become visible without requiring users to clear their browser cache.
Supported features [#supported-features]
| Capability | Support | Notes |
| ---------------------------- | ------------------------------ | ------------------------------------------------------ |
| Static sites | Supported | Build output is served through the Easel CDN |
| Single-page applications | Supported with configuration | Requires a fallback rewrite to `index.html` |
| React | Supported | Includes standard Vite React projects |
| Vue | Supported | Includes standard Vite Vue projects |
| Preact | Supported | Includes standard Vite Preact projects |
| Solid | Supported | Includes standard Vite Solid projects |
| Svelte | Supported | For client-rendered Svelte applications |
| TypeScript | Supported | Compiled through the Vite build |
| CSS modules | Supported | Processed during the build |
| Static asset imports | Supported | Emitted into the build output |
| Files from `public` | Supported | Copied to the output root |
| Custom base paths | Supported | Configure with Vite’s `base` option |
| Client environment variables | Supported | Variables must use the `VITE_` prefix |
| Monorepos | Supported | Configure the project root directory |
| Custom output directory | Supported | Configure the same directory in Vite and Easel |
| Redirects and rewrites | Supported | Defined in project configuration |
| Custom response headers | Supported | Defined in project configuration |
| Server-Side Rendering | Not provided by plain Vite | Use a supported full-stack framework |
| API routes | Not provided by plain Vite | Deploy an Easel Function or use a full-stack framework |
| Middleware | Not provided by plain Vite | Use Easel routing and security configuration |
| WebSockets | Not provided by static hosting | Requires a persistent external service |
Single-page applications [#single-page-applications]
Client-side routers use browser history APIs to render multiple routes from one HTML entry point.
For example, a React application may handle all of these routes in the browser:
```text
/account
/account/settings
/projects/123
```
When a visitor opens `/account/settings` directly, Easel must serve `index.html` rather than look for a file at that path.
Add a fallback rewrite in `vercel.json` at the project root. Easel accepts this portable routing format:
```json title="vercel.json"
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"rewrites": [
{
"source": "/(.*)",
"destination": "/index.html"
}
]
}
```
Easel applies the rewrite only when handling the request. The browser URL remains unchanged, allowing the client-side router to render the requested route.
Avoid rewriting static assets [#avoid-rewriting-static-assets]
A broad SPA fallback should run after Easel checks for a matching static file. Requests for JavaScript, CSS, images, fonts, and other generated assets continue to resolve to their files.
A missing application route receives `index.html`, while a missing asset should still return a `404` response.
Framework routers [#framework-routers]
The same fallback model works with common client-side routers, including:
* React Router in declarative or data mode
* Vue Router
* TanStack Router
* Solid Router
* Preact Router
* Svelte SPA routers
React Router framework mode includes a server build and should instead use the [React Router framework guide](/docs/framework-guides/react-router).
Static sites with multiple HTML pages [#static-sites-with-multiple-html-pages]
Not every Vite application is a single-page application.
Vite can produce multiple HTML entry points:
```ts
import { resolve } from "node:path";
import { defineConfig } from "vite";
export default defineConfig({
build: {
rollupOptions: {
input: {
home: resolve(__dirname, "index.html"),
about: resolve(__dirname, "about/index.html"),
pricing: resolve(__dirname, "pricing/index.html"),
},
},
},
});
```
Easel deploys each generated HTML file at its corresponding path:
| Generated file | URL |
| ------------------------- | ----------- |
| `dist/index.html` | `/` |
| `dist/about/index.html` | `/about/` |
| `dist/pricing/index.html` | `/pricing/` |
Do not add an SPA fallback rewrite when each route has its own generated HTML file.
Environment variables [#environment-variables]
Vite exposes variables prefixed with `VITE_` to application code through `import.meta.env`.
Configure the variable in the Easel dashboard or CLI. See [deployment environments](/docs/deployments/environments).
```text
VITE_API_ORIGIN=https://api.example.com
```
Read it in the application:
```ts
const apiOrigin = import.meta.env.VITE_API_ORIGIN;
```
Public variables [#public-variables]
Every variable exposed through `import.meta.env` is included in the browser bundle.
Do not place secrets in variables prefixed with `VITE_`, including:
* Database credentials
* Private API keys
* Signing keys
* Service-account credentials
* Authentication secrets
A visitor can inspect these values in downloaded JavaScript.
Use an Easel Function or another server-side service when an operation requires a secret.
Build-time behavior [#build-time-behavior]
Vite replaces client environment variables during the production build. Changing a `VITE_` variable requires a new deployment.
Use separate environment values for production, preview, and development when the application connects to different services in each environment.
Built-in variables [#built-in-variables]
Vite also provides built-in environment values:
```ts
import.meta.env.MODE;
import.meta.env.BASE_URL;
import.meta.env.PROD;
import.meta.env.DEV;
import.meta.env.SSR;
```
For a static Easel deployment, `import.meta.env.SSR` is false in browser application code.
Base paths [#base-paths]
Vite assumes the application is served from `/` unless you configure a different base path.
For an application deployed at:
```text
https://example.com/dashboard/
```
set `base` in `vite.config.ts`:
```ts
import { defineConfig } from "vite";
export default defineConfig({
base: "/dashboard/",
});
```
Vite prefixes generated JavaScript, CSS, and asset URLs with that path.
The Easel deployment route and Vite base path must agree. A mismatch commonly causes the HTML page to load while JavaScript or CSS requests return `404`.
For a root-domain deployment, leave the default base:
```ts
import { defineConfig } from "vite";
export default defineConfig({
base: "/",
});
```
Asset handling [#asset-handling]
Imported assets [#imported-assets]
Vite processes assets imported from source code:
```ts
import logoUrl from "./logo.svg";
```
Small assets may be embedded into JavaScript or CSS. Larger assets are emitted into the output directory with content-hashed filenames.
Easel treats these hashed files as immutable CDN assets.
Public directory [#public-directory]
Files placed in Vite’s `public` directory are copied to the root of the build output without content hashing.
For example:
```text
public/favicon.ico
```
becomes:
```text
dist/favicon.ico
```
and is available at:
```text
/favicon.ico
```
Because public files do not receive content hashes, update their filenames when you need to guarantee immediate cache invalidation.
Source maps [#source-maps]
Vite does not emit production source maps by default.
Enable them in `vite.config.ts`:
```ts
import { defineConfig } from "vite";
export default defineConfig({
build: {
sourcemap: true,
},
});
```
Source maps may contain original application source. Upload them to your error-monitoring provider or restrict their public availability when exposing source code is a concern.
Cache behavior [#cache-behavior]
Vite generates content-hashed filenames such as:
```text
assets/index-Cg4kP8nD.js
assets/index-D7hA2xLm.css
```
Because the filename changes whenever its contents change, Easel can cache these assets aggressively. See [Cache responses at the edge](/docs/cdn/caching).
A Vite deployment uses different policies for different resources:
| Resource | Behavior |
| ------------------------- | -------------------------------------------- |
| Hashed JavaScript and CSS | Long-lived immutable caching |
| Hashed images and fonts | Long-lived immutable caching |
| HTML entry points | Shorter caching with revalidation |
| Files from `public` | Configurable, depending on filename strategy |
Easel deployments are atomic. A new deployment publishes a complete new set of assets rather than updating files in place.
Older deployment URLs continue pointing to their original asset set, which prevents a preview or rollback from accidentally loading bundles from another deployment.
Redirects, rewrites, and headers [#redirects-rewrites-and-headers]
Vite does not define production routing behavior itself. Configure application-level routing in project configuration.
Common use cases include:
* Redirecting an old route to a new route
* Rewriting SPA routes to `index.html`
* Adding security headers
* Defining cache behavior
* Proxying a path to another service
* Redirecting between apex and `www` domains
For example, redirect an old documentation path:
```json title="vercel.json"
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"redirects": [
{
"source": "/docs-old/:path*",
"destination": "/docs/:path*",
"status": 308
}
]
}
```
Add security headers:
```json title="vercel.json"
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"headers": [
{
"source": "/(.*)",
"headers": [
{
"key": "X-Content-Type-Options",
"value": "nosniff"
},
{
"key": "Referrer-Policy",
"value": "strict-origin-when-cross-origin"
}
]
}
]
}
```
When importing an existing project, Easel can also interpret supported configuration formats from compatible platforms.
APIs and server-side code [#apis-and-server-side-code]
Plain Vite applications contain browser code and static assets. Vite does not create an application server or API runtime.
When the application requires server-side behavior, you can:
* Deploy an Easel Function
* Connect to an external API
* Use a supported full-stack framework
* Use a managed backend or database service
Do not place private credentials directly in the Vite application to call a protected upstream API. Browser users can inspect those credentials and make requests independently of the application.
An Easel Function can keep the credential server-side:
```ts
export default async function handler(request: Request) {
const response = await fetch("https://api.example.com/private-data", {
headers: {
Authorization: `Bearer ${process.env.PRIVATE_API_KEY}`,
},
});
return new Response(response.body, {
status: response.status,
headers: {
"Content-Type":
response.headers.get("Content-Type") ?? "application/json",
},
});
}
```
The Vite application can then call the function using a relative URL:
```ts
const response = await fetch("/api/private-data");
const data = await response.json();
```
Monorepos [#monorepos]
Set the Easel project root to the directory containing the Vite application.
For example:
```text
apps/
dashboard/
package.json
vite.config.ts
api/
package.json
packages/
ui/
package.json
```
The Vite project root would be:
```text
apps/dashboard
```
Easel runs the install and build commands from the configured project context while preserving access to workspace dependencies.
Ensure the package manager’s lockfile is available from that context. Depending on the workspace layout, the install command may need to run from the repository root even when the build command targets a nested application.
Custom output directories [#custom-output-directories]
Vite writes production files to `dist` by default.
To use another directory:
```ts
import { defineConfig } from "vite";
export default defineConfig({
build: {
outDir: "build",
},
});
```
Set the Easel output directory to the same value:
```text
build
```
If these settings differ, the build can succeed while Easel reports that it cannot find deployable output.
Avoid writing the build output outside the project workspace unless the Easel build environment explicitly permits that path.
Local development [#local-development]
Continue using Vite’s development server:
```bash
npm run dev
```
Vite’s development server provides hot module replacement and framework-specific development behavior.
Use Easel preview deployments to validate production platform behavior, including:
* Production minification and bundling
* SPA fallback rewrites
* Redirects and custom headers
* CDN caching
* Environment-specific variables
* Base paths
* WAF and security rules
* Custom domains
A preview deployment runs the same static deployment process as production and receives its own immutable URL.
Do not use `vite preview` as a production server. It is intended only for locally previewing the generated build output.
Static export from other frameworks [#static-export-from-other-frameworks]
Some frameworks can emit fully static output through Vite or a related build process.
A static export can be deployed through the Vite path when the final output consists only of HTML, JavaScript, CSS, and other static files.
However, using a static export removes server-dependent framework features such as:
* Server-Side Rendering
* Server Actions
* API routes
* Middleware
* Runtime cache revalidation
* Request-time personalization
Use the framework’s dedicated Easel guide when the application requires any server runtime behavior.
Known limitations [#known-limitations]
No server runtime [#no-server-runtime]
A plain Vite deployment does not include a Node.js or edge server. Server-only modules and Node.js APIs cannot run in browser code.
For example, the following cannot execute in the deployed frontend:
```ts
import fs from "node:fs";
```
Move server-side logic into an Easel Function or a supported full-stack framework.
No hidden environment variables [#no-hidden-environment-variables]
Variables included in the Vite client bundle are public. The `VITE_` prefix controls browser exposure. It is not a secret-storage mechanism.
Client-side routing requires a rewrite [#client-side-routing-requires-a-rewrite]
History-based routes return `404` on direct navigation unless an SPA fallback is configured.
Hash-based routing does not require a server rewrite because the URL fragment is not sent in the HTTP request, but history-based routing produces cleaner URLs.
Filesystem paths are case-sensitive [#filesystem-paths-are-case-sensitive]
The Easel build environment and CDN treat file paths as case-sensitive.
An import that works on a case-insensitive local filesystem may fail during deployment:
```ts
// File is named Button.tsx
import Button from "./button";
```
Ensure import casing exactly matches the filename.
Troubleshooting [#troubleshooting]
The build succeeds, but Easel cannot find the output [#the-build-succeeds-but-easel-cannot-find-the-output]
Confirm that the Easel output directory matches Vite’s `build.outDir`.
The default for both should be:
```text
dist
```
A client-side route returns 404 [#a-client-side-route-returns-404]
Configure an SPA fallback rewrite to `index.html`.
Do not add this rewrite to a multipage site where each route has its own generated HTML file.
The page loads without JavaScript or styles [#the-page-loads-without-javascript-or-styles]
Check the browser network panel for asset requests returning `404`.
The most common cause is a mismatch between Vite’s `base` setting and the application’s deployment path.
An environment variable is undefined [#an-environment-variable-is-undefined]
Confirm that:
1. The variable begins with `VITE_`.
2. It is configured for the current deployment environment.
3. The application was rebuilt after the value was added or changed.
4. The code reads it through `import.meta.env`.
For example:
```ts
const apiOrigin = import.meta.env.VITE_API_ORIGIN;
```
A variable still has its previous value [#a-variable-still-has-its-previous-value]
Vite embeds client environment variables during the build. Trigger a new deployment after changing the value.
An import works locally but fails during deployment [#an-import-works-locally-but-fails-during-deployment]
Check filename casing and verify that the dependency is declared in the appropriate `package.json`.
Also confirm that the package is not relying on Node.js APIs in browser code.
Refreshing a route returns the home page incorrectly [#refreshing-a-route-returns-the-home-page-incorrectly]
A broad SPA fallback sends all unmatched routes to `index.html`. Ensure APIs, static files, and other special paths are handled before the fallback rule.
The application calls the wrong API in preview deployments [#the-application-calls-the-wrong-api-in-preview-deployments]
Use separate production and preview values for `VITE_API_ORIGIN`, or call a same-origin relative path when the backend is deployed with the application.
Compatibility policy [#compatibility-policy]
Easel tests its Vite integration against representative applications using React, Vue, TypeScript, static assets, client-side routing, custom output directories, base paths, environment variables, and monorepo layouts.
Stable Vite releases may work beyond the version listed at the top of this page, but the listed version is the most recently verified baseline.
Vite plugins that only transform the build output work without platform-specific support. Plugins that expect a persistent server, custom development middleware, or a specific hosting runtime may require an Easel integration or a dedicated framework guide.
Next steps [#next-steps]
Cache headers and edge behavior
First deploy from Git
CLI deploy options
# Function configuration
Function configuration controls the runtime, resources, environment, and
duration used by dynamic application routes.
Easel derives defaults from the framework build and project settings. Override
them only when the application has a specific requirement.
Configuration sources [#configuration-sources]
Function behavior may be influenced by:
1. Easel project settings
2. Environment-specific project settings
3. Supported framework build metadata (including route `maxDuration`)
4. Platform defaults
Easel project settings remain authoritative for platform-managed resources such
as CPU tier and Node.js version.
Project-level controls [#project-level-controls]
Project settings that affect functions include:
* Node.js version (22 or 24)
* CPU tier (Standard or Performance)
* Environment variables
* Root directory
* Build command
* Install command
There is no project UI for function duration or regions. Duration comes from
framework route config when present. Functions run in US East. See
[Function regions](/docs/functions/regions).
Runtime version [#runtime-version]
Select Node.js **22** or **24** in project build settings.
Easel does not resolve the runtime from `package.json` `engines.node`. Set the
version in the project so builds and functions use the same Node.js line.
Before changing runtime versions:
* Review framework compatibility
* Rebuild native dependencies
* Test preview deployments
* Confirm database and SDK support
* Review deprecated runtime APIs
CPU and memory [#cpu-and-memory]
CPU and memory determine the resources available to each active function
instance.
Easel currently offers two project-level tiers:
| Tier | Memory | CPU |
| ----------- | ------ | ------ |
| Standard | 2 GB | 1 vCPU |
| Performance | 4 GB | 2 vCPU |
Increase resources when the function:
* Performs CPU-intensive work
* Uses large framework bundles
* Processes large responses
* Requires substantial in-memory data
* Encounters memory errors
* Needs lower latency for compute-bound work
Do not increase memory merely to compensate for:
* Unbounded caches
* Memory leaks
* Loading unnecessary dependencies
* Buffering large streams
* Retaining request state globally
See [Function limits](/docs/functions/limits) for related constraints.
Maximum duration [#maximum-duration]
Maximum duration controls how long an invocation may remain active.
Duration includes:
* Application execution
* Awaited network calls
* Streaming
* Registered post-response work (`waitUntil` / `after()`)
* Other work performed before the invocation ends
The default maximum duration is **30s**. Frameworks that emit `maxDuration` in
build output (for example Next.js route config) can raise it up to **800s**.
Next.js example:
```ts
export const runtime = "nodejs";
export const maxDuration = 60;
```
Easel reads the value from `.vc-config.json` produced by the build. Missing or
invalid values default to 30s. Values outside 1–800 are clamped.
Choose a duration that allows normal requests to complete without masking
unexpectedly slow operations.
Use a durable background-job system for work that exceeds practical HTTP request
duration.
Environment variables [#environment-variables]
Configure environment variables separately for supported deployment
environments.
Typical environments include:
* Production
* Preview
* Development
Example server-only variables:
```text
DATABASE_URL
AUTH_SECRET
API_KEY
```
Example public variables:
```text
NEXT_PUBLIC_API_ORIGIN
VITE_PUBLIC_API_ORIGIN
```
Public variables can be embedded into browser code during the build. They must
not contain secrets.
See [Deployment environments](/docs/deployments/environments).
Build-time and runtime variables [#build-time-and-runtime-variables]
Some variables are used during the build, while others are read when the
function runs.
A variable may need to be available in both phases.
Framework behavior differs, so consult the relevant
[framework guide](/docs/framework-guides).
Secret changes [#secret-changes]
A runtime variable change may require a new deployment depending on how the
framework packages or reads the value.
Public build-time variables require a rebuild.
Framework-generated configuration [#framework-generated-configuration]
Framework adapters can emit metadata describing:
* Function entry points
* Route patterns
* Runtime requirements
* Route-level duration
* Static assets
* Cache behavior
Easel consumes supported metadata from the build output.
Platform-level settings can override adapter resource hints where documented.
Root directory [#root-directory]
For monorepos, set the project root to the directory containing the application.
Example:
```text
repository/
├── apps/
│ ├── web/
│ │ ├── package.json
│ │ └── next.config.ts
│ └── admin/
└── packages/
```
For the web application:
```text
Root directory: apps/web
```
The root affects:
* Dependency installation
* Framework detection
* Build commands
* Output discovery
* Environment files
* Application configuration
Install command [#install-command]
Easel normally detects the package manager and install command.
Examples:
```bash
npm install
pnpm install
yarn install
bun install
```
Override the command only when the repository requires custom behavior.
Use lockfiles to keep dependency resolution reproducible.
Build command [#build-command]
Easel normally uses the framework’s production build command.
Examples:
```bash
next build
nuxt build
vite build
```
The build must produce a supported deployment output.
Do not start a long-running server from the build command.
Native dependencies [#native-dependencies]
Packages with native components must be compatible with the Easel runtime
environment.
Potential issues include:
* Operating-system compatibility
* CPU architecture
* C library requirements
* Post-install scripts
* Prebuilt binary availability
* Runtime version compatibility
Test native dependencies in a preview deployment.
Configuration by environment [#configuration-by-environment]
Production and preview deployments may need different:
* Database connections
* Authentication origins
* API keys
* Logging levels
* External service environments
* Resource allocations
Avoid branching on hostnames when a deployment environment variable is
available.
Safe defaults [#safe-defaults]
Start with platform defaults when:
* The application is new
* Traffic is low
* Workloads are mostly I/O-bound
* The framework has no special resource requirement
Adjust settings after observing:
* Duration
* Memory
* CPU
* Startup latency
* Concurrent load
* Downstream latency
Configuration changes [#configuration-changes]
A change to runtime, resources, or environment variables may require a new
deployment.
Use a preview deployment to validate changes before promoting them to
production.
Troubleshooting [#troubleshooting]
The configured runtime is ignored [#the-configured-runtime-is-ignored]
Check whether:
* The Node.js version is set in project build settings (not only `engines`)
* The runtime version is supported
* The setting requires a new deployment
* The configuration is applied to the correct environment
A function runs out of memory [#a-function-runs-out-of-memory]
Check for:
* Large in-memory buffers
* Unbounded collections
* Module-level caches
* Large response generation
* Native-library memory usage
* Excessive concurrency
* Memory leaks
Increasing memory may help, but inspect application behavior first.
The function times out [#the-function-times-out]
Use traces and logs to identify:
* Slow database queries
* External API delays
* Retry loops
* Unclosed streams
* Post-response work
* Long-running CPU tasks
Raise route `maxDuration` only when the operation is appropriate for a
request-driven function, and stay within the 800s maximum.
Environment variables are missing [#environment-variables-are-missing]
Confirm that:
* The variable exists in the correct environment
* The deployment was created after the variable changed
* The framework exposes it at runtime
* Public prefixes are used only for non-secret client values
* The variable name matches exactly
Related documentation [#related-documentation]
* [Functions](/docs/functions)
* [Function runtime](/docs/functions/runtime)
* [Function regions](/docs/functions/regions)
* [Function limits](/docs/functions/limits)
* [Framework guides](/docs/framework-guides)
* [Deployment URLs](/docs/deployments/urls)
* [Deployment environments](/docs/deployments/environments)
# Functions
Easel Functions run the server-side portions of your application, including
server-rendered pages, API routes, server actions, loaders, framework endpoints,
and application-defined handlers.
Functions are created automatically from supported framework builds. Easel
deploys each function with the runtime and resources required by the project.
Functions run in US East; see [Function regions](/docs/functions/regions).
What runs in a function [#what-runs-in-a-function]
Depending on the framework and application, Easel Functions can handle:
* Server-rendered pages
* API routes
* Route handlers
* Server Actions
* Loaders and actions
* Webhooks
* Authentication callbacks
* Cache regeneration
* Scheduled post-response work within the invocation lifecycle
* Application-defined HTTP endpoints
Static pages and build assets do not require a function. They are served through
Easel’s CDN.
How requests reach functions [#how-requests-reach-functions]
A dynamic request enters through Easel’s delivery network and is routed to an
eligible function instance.
A function is not invoked when Easel can complete the request through:
* A firewall rule
* A redirect
* A fresh cached response
* A static deployment asset
See [CDN](/docs/cdn) for request delivery and response caching.
Framework integration [#framework-integration]
Supported frameworks generate the function entry points Easel deploys.
Examples include:
| Framework behavior | Function workload |
| ------------------------------ | ----------------------- |
| Next.js Server Component route | Server rendering |
| Next.js Route Handler | HTTP endpoint |
| SvelteKit `+page.server` load | Server data loading |
| SvelteKit form action | Form submission |
| Nuxt server route | Nitro server handler |
| React Router loader or action | Server data or mutation |
| TanStack Start server function | Server handler |
The exact number and structure of deployed functions depend on the framework
adapter and build output.
See [Framework guides](/docs/framework-guides) for framework-specific deployment
behavior.
Scaling [#scaling]
Easel creates additional function capacity as request volume increases.
Applications must not assume that:
* The same visitor reaches the same instance
* Requests run sequentially
* Local memory is shared across instances
* Files written by one invocation exist during another
* An instance remains active indefinitely
Use a database, object storage, or the [Runtime Cache](/docs/runtime-cache) for
shared or durable data.
In-function concurrency [#in-function-concurrency]
An active Easel Function can process more than one request concurrently when the
runtime and application permit it.
This can improve:
* Throughput per active instance
* Resource utilization
* Connection reuse
* Latency during traffic bursts
* Performance for applications that spend time waiting on databases or APIs
Application code must therefore be safe for overlapping requests.
Avoid storing request-specific state in module-level mutable variables.
Unsafe:
```ts
let currentUserId: string | undefined;
export async function handler(request: Request) {
currentUserId = await getUserId(request);
return Response.json({
userId: currentUserId,
});
}
```
Safer:
```ts
export async function handler(request: Request) {
const userId = await getUserId(request);
return Response.json({
userId,
});
}
```
Module-level read-only objects and reusable clients are appropriate when their
libraries support concurrent use.
Streaming [#streaming]
Functions can return streaming HTTP responses when supported by the framework
and runtime.
```ts
export async function GET() {
const stream = new ReadableStream({
start(controller) {
controller.enqueue(new TextEncoder().encode("Starting\n"));
controller.enqueue(new TextEncoder().encode("Complete\n"));
controller.close();
},
});
return new Response(stream, {
headers: {
"Content-Type": "text/plain; charset=utf-8",
},
});
}
```
Easel forwards response chunks as they become available.
The function invocation remains active until application execution finishes, the
response closes, or the invocation reaches its duration limit.
Streaming does not automatically make a response cacheable. See
[Caching](/docs/cdn/caching).
Work after the response [#work-after-the-response]
Supported framework APIs may register work that continues after the response is
ready. That work still counts against Function duration and does not outlive the
invocation.
See [Background work](/docs/runtime/background-work) for patterns, limits, and
when to use a durable job system instead.
Environment variables [#environment-variables]
Functions receive environment variables configured for the project and
deployment environment. See
[Environment variables](/docs/runtime/environment-variables) for scoping,
secrets, and build-time versus runtime values.
```ts
const databaseUrl = process.env.DATABASE_URL;
```
Production and preview deployments can use different values.
Public framework variables such as `NEXT_PUBLIC_*` or `VITE_*` may be embedded
into browser bundles during the build and must not contain secrets.
See [Function configuration](/docs/functions/configuration).
Observability [#observability]
Function requests can produce:
* Request logs
* Application logs
* Errors
* Duration and resource metrics
* Distributed traces
* Cache diagnostics
* Regional execution metadata
Use the request ID returned by Easel to correlate a client response with logs
and traces:
```http
X-Easel-Id: 550e8400-e29b-41d4-a716-446655440000
```
Avoid logging authorization tokens, session cookies, passwords, API keys, or
other secrets.
See [Observability](/docs/observability) and
[Request details](/docs/observability/request-details).
Functions and caching [#functions-and-caching]
Functions can interact with two distinct cache layers.
| CDN cache | Runtime Cache |
| -------------------------------------- | ------------------------------------- |
| Stores complete HTTP responses | Stores application values |
| Evaluated before a function is invoked | Accessed from function code |
| Controlled through HTTP cache headers | Controlled through an application API |
| Best for pages and API responses | Best for data and computed results |
A function can read application data from the Runtime Cache and return a
response that is subsequently stored in the CDN cache.
See:
* [Caching](/docs/cdn/caching)
* [Revalidation and purging](/docs/cdn/revalidation)
* [Runtime Cache](/docs/runtime-cache)
Function configuration [#function-configuration]
Project settings control function behavior such as:
* Node.js version
* CPU and memory allocation
* Environment variables
* Build and output settings
Framework adapters may also emit route-level metadata such as `maxDuration`.
Functions run in US East. See [Function regions](/docs/functions/regions).
See [Function configuration](/docs/functions/configuration).
Regions [#regions]
Functions run in US East (`iad`). The CDN may still serve cacheable responses
from other edge locations.
See [Function regions](/docs/functions/regions).
Limits [#limits]
Functions are subject to limits including:
* Maximum duration
* Memory
* CPU
* Request body size
* Response size
* Header size
* Deployment size
* Concurrent executions
See [Function limits](/docs/functions/limits).
Related documentation [#related-documentation]
* [Runtime behavior](/docs/functions/runtime)
* [Function configuration](/docs/functions/configuration)
* [Function regions](/docs/functions/regions)
* [Function limits](/docs/functions/limits)
* [Environment variables](/docs/runtime/environment-variables)
* [Background work](/docs/runtime/background-work)
* [Image optimization](/docs/runtime/image-optimization)
* [Runtime Cache](/docs/runtime-cache)
* [Framework guides](/docs/framework-guides)
* [CDN](/docs/cdn)
* [Observability](/docs/observability)
# Function limits
Easel Functions are subject to resource and request limits that protect platform
reliability and define the supported execution model.
Current limits [#current-limits]
| Limit | Value | Notes |
| ----------------------------- | ---------------- | ----------------------------------------- |
| Default maximum duration | 30s | Includes streaming and post-response work |
| Maximum configurable duration | 800s | Upper bound for customer `maxDuration` |
| Memory | 2 GB or 4 GB | Standard or Performance CPU tier |
| CPU | 1 vCPU or 2 vCPU | Paired with the memory tier |
| Request body size | 10 MB | Larger uploads must use object storage |
| Deployment bundle size | 250 MB | Packaged function zip |
| Environment variables | 4 KB total | Combined size of names and values |
| Incoming WebSockets | Not supported | Use streaming HTTP or SSE where needed |
In-function concurrency, response size, header size, URL length, temporary
filesystem capacity, and outbound connection counts are enforced by the platform
and can change with runtime configuration. Design applications so they remain
safe under concurrent requests on a shared instance.
Duration [#duration]
Maximum duration is the total time an invocation can remain active.
It includes:
* Application execution
* Database and API requests
* Streaming response bodies
* Post-response work such as `waitUntil` / `after()`
* Framework rendering
* Cache regeneration
Returning response headers does not end the invocation. Duration continues until
the handler finishes, the stream closes, and registered post-response work
completes, or the limit is reached.
When the duration limit is reached, Easel terminates the invocation.
Stalled invokes are aborted earlier, without waiting for the full
`maxDuration`:
* Response headers must arrive within **60 seconds** of invoke start (or
sooner when remaining `maxDuration` plus a small transport slack is smaller).
* After headers, each body chunk and completion signal must arrive within
**30 seconds** of the previous progress (again capped by the remaining
duration budget).
Set route-level duration through your framework when supported (for example
Next.js `export const maxDuration = 60`). Easel reads the value from build
output. The default is 30s when unset. Values outside 1–800s are clamped.
Use a queue or durable worker system for work that cannot reliably complete
within the limit.
Memory [#memory]
Memory includes application and runtime usage such as:
* JavaScript heap
* Native allocations
* Framework code
* Buffers
* Loaded files
* Database clients
* Concurrent request state
An invocation or instance that exceeds its memory allowance may terminate.
Common causes include:
* Unbounded arrays or maps
* Large body buffering
* Image processing
* Loading large datasets
* Retaining request state globally
* Memory leaks
* Excessive concurrency
Stream large data where possible rather than loading it entirely into memory.
CPU [#cpu]
CPU allocation affects compute-bound work.
Examples include:
* Rendering
* Compression
* Cryptography
* Serialization
* Image processing
* Large data transformations
I/O-bound applications may benefit more from concurrency and connection reuse
than from increased CPU.
CPU and memory are configured together through the Standard and Performance
tiers. See [Function configuration](/docs/functions/configuration).
In-function concurrency [#in-function-concurrency]
Concurrency limits the number of simultaneous requests one active instance can
process.
Higher concurrency can improve efficiency for I/O-heavy workloads but increases
aggregate pressure on:
* Memory
* CPU
* Database pools
* External API limits
* Shared application clients
Applications must remain concurrency-safe even below the platform maximum.
The platform may use fewer concurrent requests depending on traffic and instance
conditions.
Request body size [#request-body-size]
Requests larger than the supported body limit may be rejected before or during
function execution.
For large uploads, prefer direct browser-to-object-storage uploads using signed
URLs.
This avoids sending the complete file through the function.
Response size [#response-size]
Buffered and streaming responses may have different practical limits.
Large buffered responses consume memory and delay the first byte.
Prefer streaming when:
* Generating large exports
* Forwarding large upstream responses
* Producing incremental output
For static or generated files that are reused, store the file in object storage
or deploy it as a static asset instead of regenerating it on each request.
Headers [#headers]
Requests with oversized headers can be rejected before application code runs.
Common causes include:
* Large cookies
* Excessive authentication claims
* Many tracing headers
* Repeated proxy headers
* Large custom metadata
Keep cookies small and avoid storing complete application state in them.
Responses can also fail when custom headers exceed platform limits.
URL length [#url-length]
Long URLs commonly result from:
* Large query payloads
* Encoded state
* Complex filters
* Tracking data
* Redirect chains
Use a request body for large structured input rather than encoding it into the
URL.
Remember that `GET` request bodies are not a reliable alternative.
Temporary filesystem [#temporary-filesystem]
Temporary storage is ephemeral and capacity-limited.
Use it only for bounded intermediate work.
Do not use it for:
* Persistent uploads
* Durable databases
* Shared application state
* Long-term caches
Files can disappear when the invocation or instance ends.
Bundle size [#bundle-size]
Function bundles include:
* Application code
* Framework runtime
* Dependencies
* Generated server code
* Packaged files
Large bundles can increase:
* Build time
* Deployment size
* Startup latency
* Memory usage
Reduce bundle size by:
* Removing unused dependencies
* Avoiding large optional packages
* Using framework output tracing
* Loading assets from object storage
* Separating unrelated workloads
* Reviewing duplicated dependencies
Environment variable limits [#environment-variable-limits]
Environment variables have limits on count, name size, value size, and aggregate
size. The combined size of environment variable names and values must stay within
4 KB.
Do not store large files, certificates, or datasets directly in environment
variables.
Use a secret manager or secure storage for larger configuration objects where
supported.
Logs [#logs]
Large or excessively frequent logs can be truncated, sampled, or rejected.
Avoid logging:
* Complete request bodies
* Large response payloads
* Binary data
* Secrets
* Session cookies
* Authorization headers
Prefer structured, concise events.
Database connections [#database-connections]
Function concurrency and autoscaling can create many database connections.
For example:
```text
instances × concurrent requests × connections per request
```
can exceed the database limit quickly.
Use:
* Connection pools designed for serverless workloads
* Database proxies
* Shared clients within an instance
* Bounded pool sizes
* Query timeouts
* Runtime Cache
* CDN caching
Do not create a new unbounded pool for every request.
External service limits [#external-service-limits]
Easel’s function limits do not replace limits imposed by:
* Databases
* APIs
* Authentication providers
* Email services
* Object storage
* Payment services
Autoscaling can increase downstream request volume rapidly.
Use rate limits, bounded concurrency, retries with backoff, and circuit breakers
where appropriate.
Cacheable response limits [#cacheable-response-limits]
CDN caching may impose separate constraints on:
* Response size
* Status codes
* Headers
* Streaming
* TTL
* Tags
See [Caching](/docs/cdn/caching) for CDN-specific behavior.
Limits and framework behavior [#limits-and-framework-behavior]
Frameworks can introduce their own limits and defaults.
Examples include:
* Body parser limits
* Image optimization limits
* Route-level duration
* Static generation limits
* Middleware restrictions
* Adapter bundle constraints
The effective limit is the strictest applicable framework or platform
constraint.
Limit errors [#limit-errors]
When a limit is exceeded, the request may fail with:
* An HTTP error status
* A platform error page
* A function termination
* A truncated log or response
* A build failure
Use logs, traces, and the request ID (`X-Easel-Id`) to identify which limit was
exceeded, then adjust configuration or application behavior.
Related documentation [#related-documentation]
* [Functions](/docs/functions)
* [Function runtime](/docs/functions/runtime)
* [Function configuration](/docs/functions/configuration)
* [Function regions](/docs/functions/regions)
* [Caching](/docs/cdn/caching)
* [Runtime Cache](/docs/runtime-cache)
# Function regions
Easel Functions run in a single compute region: US East (`iad` / `us-east-1`).
The CDN can still serve cached and static responses from edge locations near
visitors. Dynamic requests that need application code run in US East.
Delivery network and compute [#delivery-network-and-compute]
Easel’s delivery network and function compute are related but distinct.
A visitor can enter the CDN near their location while the application function
runs in US East.
Cached responses and static assets may complete without invoking a function.
Available region [#available-region]
| Region | Identifier | Location |
| ------- | ---------- | -------------------------------- |
| US East | `iad` | Northern Virginia, United States |
Use `iad` as the public region identifier in diagnostics and application code
that reads platform headers.
Additional function regions are not available yet.
Latency and databases [#latency-and-databases]
Place databases and other stateful dependencies close to US East when
request-driven work depends on them.
Example:
```text
User in London
↓
Easel CDN (near the user)
↓
Function in US East (iad)
↓
Database in US East
```
Colocating the function and database usually matters more than placing compute
near the user when every request queries a single primary database.
Reduce round trips through:
* Query batching
* Joins
* Transactions
* Connection pooling
* Runtime Cache
* CDN response caching
Reading the region on requests [#reading-the-region-on-requests]
Easel attaches the function region on the request your application code receives:
```http
X-Easel-Function-Region: iad
```
Read it from the framework request API or raw headers:
```ts
export async function GET(request: Request) {
const region = request.headers.get("x-easel-function-region");
return Response.json({ region });
}
```
Treat this as platform metadata on the **request**, not as a value you set from
the client. Client-supplied `X-Easel-Function-Region` values do not control
routing.
See [Request and response headers](/docs/cdn/headers).
Sessions and local state [#sessions-and-local-state]
Do not store sessions only in local function memory.
Use:
* Signed stateless cookies
* A shared session store
* A database
* Another durable authentication system
Instances remain ephemeral and independently scalable even within one region.
Caching before compute [#caching-before-compute]
CDN caching can reduce the impact of function-region distance for cacheable
routes.
A cached response can be served without invoking the function.
Use CDN caching for:
* Public pages
* Product catalogs
* Documentation
* Public API responses
* Generated content that tolerates controlled staleness
Use the Runtime Cache to reduce repeated application-data work within functions.
Related documentation [#related-documentation]
* [Functions](/docs/functions)
* [Function runtime](/docs/functions/runtime)
* [Function configuration](/docs/functions/configuration)
* [Function limits](/docs/functions/limits)
* [Caching](/docs/cdn/caching)
* [Runtime Cache](/docs/runtime-cache)
* [Request and response headers](/docs/cdn/headers)
# Function runtime
The function runtime provides the execution environment for server-side
application code.
This page describes instance lifecycle, concurrency, reuse, streaming,
filesystem behavior, networking, and shutdown semantics.
Runtime environment [#runtime-environment]
Easel Functions run application code produced by supported frameworks or
application-defined handlers.
A runtime environment includes:
* The application bundle
* Runtime dependencies
* Configured environment variables
* Allocated CPU and memory
* Temporary filesystem space
* Network access
* Request and observability integrations
Supported runtime versions are listed in
[Function configuration](/docs/functions/configuration).
Instance lifecycle [#instance-lifecycle]
A function instance moves through a lifecycle similar to:
Easel may create, reuse, suspend, or terminate instances based on traffic and
platform conditions.
The application must not depend on a specific instance remaining available.
Initialization [#initialization]
Initialization happens before an instance begins handling application traffic.
Typical initialization work includes:
* Loading application modules
* Initializing framework code
* Creating database clients
* Reading configuration
* Preparing reusable application state
Module-level initialization can reduce repeated work across requests:
```ts
const database = createDatabaseClient({
url: process.env.DATABASE_URL,
});
export async function handler(request: Request) {
const users = await database.query("SELECT * FROM users");
return Response.json(users);
}
```
Initialization code must remain reasonably fast. Large dependency graphs,
expensive synchronous work, and unnecessary network requests increase startup
latency.
Instance reuse [#instance-reuse]
An initialized instance may handle multiple requests over its lifetime.
Reuse allows applications to preserve:
* Loaded modules
* Database connection pools
* HTTP clients
* Parsed configuration
* Read-only lookup data
* In-memory caches used only as optional optimizations
Reuse is not guaranteed.
Code must continue working when an instance starts with no previous in-memory
state.
A warm Fluid instance may handle more than one request during a single platform
wake, but only while enough wake time remains for the route’s `maxDuration`.
Customer `maxDuration` bounds each request (including streaming and
post-response work). It is not the AWS session Timeout; that is a platform
setting that keeps the wake open long enough to multiplex eligible requests.
The platform aborts a request that makes no progress well before the full
duration budget: headers must start within 60 seconds, and body chunks must
arrive no more than 30 seconds apart (see [Function limits](/docs/functions/limits)).
The per-request wait tracks `maxDuration` rather than the longer wake Timeout.
In-function concurrency [#in-function-concurrency]
An instance may process overlapping requests.
This differs from a model in which each instance handles exactly one request at
a time.
Concurrency is especially useful for workloads that spend significant time
waiting on:
* Databases
* External APIs
* Object storage
* Network streams
* Other asynchronous services
Concurrency safety [#concurrency-safety]
Do not place request-specific state in shared mutable variables.
Avoid:
```ts
const requestContext: {
organizationId?: string;
} = {};
export async function handler(request: Request) {
requestContext.organizationId =
request.headers.get("x-organization-id") ?? undefined;
return renderOrganization(requestContext.organizationId);
}
```
Instead, keep request state local:
```ts
export async function handler(request: Request) {
const organizationId =
request.headers.get("x-organization-id") ?? undefined;
return renderOrganization(organizationId);
}
```
Libraries used as shared clients must support concurrent requests.
CPU and asynchronous work [#cpu-and-asynchronous-work]
Concurrency does not create unlimited CPU.
CPU-intensive JavaScript or native work can delay other requests handled by the
same instance.
Examples include:
* Large JSON transformations
* Image or video processing
* Compression
* Cryptographic operations
* Synchronous filesystem access
* Large template compilation
* Machine-learning inference
Move unusually expensive tasks to an appropriate worker or service when they
interfere with request latency.
Request lifecycle [#request-lifecycle]
An invocation begins when Easel assigns a request to the function runtime.
It ends when:
* Application execution completes
* The response and registered post-response work complete
* The application fails
* The client disconnect causes execution to terminate, where applicable
* The maximum duration is reached
* The platform terminates the instance
Billing and duration measurement follow the function invocation rather than only
the time until the first response byte.
Streaming responses [#streaming-responses]
A function can return a streaming response when supported by the runtime.
```ts
export async function GET() {
const encoder = new TextEncoder();
const stream = new ReadableStream({
async start(controller) {
controller.enqueue(encoder.encode("First chunk\n"));
await performAsyncWork();
controller.enqueue(encoder.encode("Second chunk\n"));
controller.close();
},
});
return new Response(stream, {
headers: {
"Content-Type": "text/plain",
},
});
}
```
Easel forwards response headers as soon as they are available, then forwards
body chunks as the runtime produces them.
The invocation remains active while the response stream is open and until
registered post-response work finishes. Streaming and `waitUntil` / `after()`
work count toward the route’s maximum duration (default 30s, max 800s).
Applications must:
* Handle cancellation where supported
* Close streams reliably
* Avoid retaining unbounded buffers
* Respect the maximum duration
* Send periodic data only when appropriate for the protocol
Some paths that need a complete body for CDN or ISR admit still buffer before
caching. Client delivery for ordinary dynamic responses streams.
Client disconnection [#client-disconnection]
A client can disconnect before the function finishes.
Applications must not assume that a successfully started request will retain an
active client connection until completion.
Use abort signals when supported:
```ts
export async function handler(request: Request) {
const result = await performWork({
signal: request.signal,
});
return Response.json(result);
}
```
Whether execution continues after a client disconnect may depend on the runtime,
framework, and response state.
Do not use client-connected requests as a substitute for durable job processing.
Work after the response [#work-after-the-response]
Framework integrations may support post-response APIs.
Registered work:
* Runs within the original invocation
* Counts toward duration
* Uses the function’s CPU and memory
* Can be interrupted if the invocation ends
* Does not provide durable retries by itself
Use this capability for short, non-critical work such as:
* Best-effort analytics
* Log enrichment
* Small cache updates
* Non-critical notifications
Do not use it for:
* Financial transactions
* Durable workflow steps
* Long-running imports
* Tasks requiring retries
* Jobs that must complete exactly once
Filesystem [#filesystem]
The function filesystem is ephemeral.
Applications can use temporary storage during an invocation where supported, but
files are not guaranteed to remain available:
* Across instances
* Across deployments
* After an instance shuts down
* For any specific retention period
Do not use the local filesystem for durable uploads, application databases, or
persistent user data.
Use object storage or another durable service.
Read-only application files [#read-only-application-files]
Files packaged into the application bundle can be read at runtime where
supported.
Avoid modifying packaged application files.
Temporary files [#temporary-files]
Temporary files may be useful for:
* Parsing uploads
* Generating intermediate output
* Working with libraries that require file paths
* Buffering bounded data
Delete temporary files when possible and remain within storage limits.
Networking [#networking]
Functions can make outbound network requests to databases, APIs, and other
services.
```ts
const response = await fetch("https://api.example.com/data");
```
Application latency depends on the network distance between the function region
(US East) and its dependencies.
Prefer persistent, reusable clients where supported.
Connections and pooling [#connections-and-pooling]
An active instance can reuse outbound connections across requests.
Examples include:
* Database pools
* HTTP keep-alive connections
* TLS sessions
* SDK clients
Create reusable clients outside the request handler:
```ts
const client = createApiClient({
apiKey: process.env.API_KEY,
});
export async function handler() {
return Response.json(await client.listItems());
}
```
Client libraries must tolerate:
* Concurrent requests
* Idle connection closure
* Instance shutdown
* Network interruption
* Reconnection
Do not assume that a connection remains open for the lifetime of the deployment.
Incoming connections [#incoming-connections]
Functions handle HTTP requests through Easel’s request interface.
Long-lived incoming WebSocket connections are not supported.
Streaming HTTP and Server-Sent Events are separate from WebSockets and remain
subject to function duration and connection limits.
Signals and shutdown [#signals-and-shutdown]
Easel may notify the runtime before termination where supported, but
applications must not depend on receiving enough time to complete important
work.
Shutdown cleanup must be best effort.
Examples include:
* Flushing buffered telemetry
* Closing clients
* Releasing temporary resources
* Stopping internal timers
Durable state must be committed before the response or through a durable
external system.
Timers and background loops [#timers-and-background-loops]
Do not start unbounded background loops from a request handler.
Avoid:
```ts
setInterval(() => {
refreshSomething();
}, 60_000);
```
The instance may stop at any time, and repeated initialization can create
multiple overlapping loops.
Use a scheduled job or durable task system for recurring work.
Short timers used during an active invocation are acceptable when they complete
within the invocation lifecycle.
Environment variables [#environment-variables]
Environment variables are available to application code according to the
deployment environment.
Do not mutate `process.env` as a way to share request state.
Treat secret variables as sensitive and avoid writing them to logs.
Time and locale [#time-and-locale]
Do not assume that the runtime’s system timezone matches the user or project
location.
Store and process timestamps in UTC unless application requirements specify
otherwise.
Format dates and times explicitly using the appropriate user locale and
timezone.
Error handling [#error-handling]
Unhandled errors fail the invocation and may return a platform or framework
error response.
Applications must:
* Catch expected failures
* Return appropriate HTTP status codes
* Avoid exposing stack traces or secrets
* Include request IDs in support workflows
* Use structured application logs
Example:
```ts
export async function GET() {
try {
const data = await loadData();
return Response.json(data);
} catch (error) {
console.error("Failed to load data", {
error,
});
return Response.json(
{
error: "Unable to load data",
},
{
status: 500,
},
);
}
}
```
Retries [#retries]
Do not assume an HTTP invocation will be retried automatically.
Clients, proxies, queues, or framework integrations may retry some requests
independently.
Application mutations must use idempotency keys when duplicate execution would
be harmful.
Runtime observability [#runtime-observability]
Runtime telemetry can include:
* Initialization duration
* Invocation duration
* Active requests
* Memory usage
* CPU usage
* Errors
* Region
* Instance identifiers
* Downstream spans
Instance identifiers are diagnostic and must not be used for application routing
or durable state.
See [Observability](/docs/observability) and
[Function observability](/docs/observability/functions).
Related documentation [#related-documentation]
* [Functions](/docs/functions)
* [Function configuration](/docs/functions/configuration)
* [Function regions](/docs/functions/regions)
* [Function limits](/docs/functions/limits)
* [Runtime Cache](/docs/runtime-cache)
* [Observability](/docs/observability)
* [Tracing](/docs/observability/tracing)
# CI/CD
Easel can deploy automatically from Git or explicitly from a CI system with the
CLI.
Choose a deployment model [#choose-a-deployment-model]
Use [Git deployments](/docs/deployments/git) when repository events should be the
source of truth. Use [CLI deploy](/docs/cli/deploy) when another system controls
release orchestration, generated source, or prebuilt output.
Avoid configuring both paths to deploy the same commit unintentionally.
Authentication [#authentication]
Authenticate non-interactive jobs with `EASEL_TOKEN` or `--token`. See
[CLI authentication](/docs/cli/authentication).
```bash
export EASEL_TOKEN=easel_…
easel whoami --format json
```
Do not print the token or include it in build artifacts.
Preview deployment [#preview-deployment]
Link the project, then create a Preview deployment:
```bash
easel link --project my-app
easel deploy --wait --format json
```
Production deployment [#production-deployment]
Create a Production deployment explicitly and promote it according to the
project's release policy:
```bash
easel deploy --prod --yes --wait --format json
```
Do not assume a Production build is already receiving production traffic when
auto-assignment is disabled. See
[Production releases](/docs/deployments/production-releases).
Deployment checks [#deployment-checks]
Before promotion, run checks against the immutable deployment URL:
* Health and smoke tests
* Authentication flows
* Critical API routes
* Cache and header validation
* Database connectivity
* Browser tests
Concurrency and cancellation [#concurrency-and-cancellation]
Cancel superseded builds where supported. Serialize production promotion to
avoid an older workflow assigning traffic after a newer workflow.
Monorepos [#monorepos]
Use changed-path detection carefully and include shared packages, lockfiles, and
root configuration in each application's dependency set. See
[Monorepos](/docs/deployments/monorepos).
# Common application patterns
Static marketing site [#static-marketing-site]
Build pages and assets ahead of time, serve them through the CDN, and use immutable caching for fingerprinted files. Add a single-page fallback only when the application uses client-side routing.
Full-stack web application [#full-stack-web-application]
Use framework-native server rendering and route handlers. Keep sessions and durable state in external services. Cache public responses and shared data independently.
JSON API [#json-api]
Validate inputs, return explicit cache headers, bound request bodies, and set timeouts for downstream services. Avoid caching authenticated responses unless the cache key safely varies by identity.
Webhook endpoint [#webhook-endpoint]
Verify the provider signature using the raw request body, persist the event or job before returning success, and make processing idempotent. Use a durable queue for work that must retry.
Authentication callback [#authentication-callback]
Keep callback routes dynamic, validate state and nonce values, use secure cookies, and avoid caching authentication responses.
Incremental regeneration [#incremental-regeneration]
Use the framework's supported revalidation APIs. Verify the resulting cache state and invalidation scope in Preview before relying on it in Production.
Database-backed page [#database-backed-page]
Reuse a concurrency-safe database client. Keep the database region compatible with the Function region and use Runtime Cache for reusable, non-sensitive query results.
File upload [#file-upload]
Prefer direct-to-object-storage uploads with signed URLs for large files. Validate metadata and authorization before issuing upload credentials.
Long-running work [#long-running-work]
Persist a job and return `202 Accepted`. Process it with a durable worker that supports retries, visibility, and idempotency rather than holding an HTTP Function open.
Gradual migration [#gradual-migration]
Use rewrites or DNS cutover to move bounded traffic to Easel. Keep the previous platform available until validation and rollback windows have passed.
# Debugging guide
Use a request-first workflow. Avoid changing multiple platform settings before identifying which layer failed.
1. Identify the deployment [#1-identify-the-deployment]
Confirm the exact URL, deployment ID, source revision, environment, and status. Reproduce against the immutable deployment URL when possible.
If the deployment URL works but the production domain does not, investigate domain assignment, DNS, TLS, or host routing rather than rebuilding the application.
2. Capture the request ID [#2-capture-the-request-id]
Inspect the response for the Easel request ID and use it to open request details, logs, traces, cache diagnostics, and security events.
```bash
curl -i https://example.com/problem-path
```
3. Determine which layer answered [#3-determine-which-layer-answered]
Check whether the request was:
* Blocked or challenged by security controls
* Redirected or rewritten
* Served from CDN cache
* Served as a static asset
* Routed to a Function
* Returned as not found
4. Inspect Function execution [#4-inspect-function-execution]
For dynamic requests, review application logs, error details, duration, memory, initialization state, region, and trace spans.
Correlate downstream database or API failures with the same trace where possible.
5. Compare environments [#5-compare-environments]
Differences between Preview and Production often come from environment variables, production-only domains, credentials, cache state, or build settings.
6. Reproduce minimally [#6-reproduce-minimally]
Reduce the failing route to its smallest input. Test without browser extensions, service workers, cached redirects, or authenticated state when relevant.
7. Check platform status and limits [#7-check-platform-status-and-limits]
Review the status page and applicable request, Function, deployment, and observability limits.
Escalation details [#escalation-details]
When contacting support, include:
* Workspace and project
* Deployment ID and URL
* Exact UTC timestamp
* Request ID
* Route and HTTP method
* Expected and actual behavior
* Reproduction steps
* Relevant logs with secrets removed
# Performance guide
Application performance on Easel depends on delivery, caching, Function execution, external dependencies, and browser behavior.
Start with request details [#start-with-request-details]
Measure before changing configuration. For a slow request, identify:
* Whether it was served from cache, static output, or a Function
* Delivery and Function region
* Function duration and initialization state
* Time spent in external databases or APIs
* Response size and compression
* Trace spans and application logs
Prefer static output [#prefer-static-output]
Generate static pages and assets when content does not require request-time execution. Static output avoids Function startup and external service latency.
Cache complete responses [#cache-complete-responses]
Use shared-cache directives for responses that can be reused. Verify the actual `X-Easel-Cache` result rather than assuming a route is cached.
Do not cache personalized responses unless the cache key safely separates users.
Cache application data [#cache-application-data]
Use Runtime Cache for database results or expensive computations that are reused across requests. Keep CDN response caching and Runtime Cache conceptually separate.
Reduce dependency latency [#reduce-dependency-latency]
Dynamic request latency often depends more on databases and external APIs than on application code. Choose compatible regions, reuse connection pools, parallelize independent calls, and set explicit timeouts.
Keep Functions concurrency-safe [#keep-functions-concurrency-safe]
Easel Functions can process overlapping requests. Reuse concurrency-safe clients, but do not store request-specific state in mutable module-level variables.
Stream intentionally [#stream-intentionally]
Streaming can improve time to first byte and perceived responsiveness, but the Function remains active until execution and response delivery finish. Streaming is not a substitute for caching or bounded execution.
Optimize assets [#optimize-assets]
* Cache fingerprinted assets for a long duration.
* Compress eligible text responses.
* Use responsive images.
* Avoid shipping unused JavaScript.
* Preload only critical resources.
Improve builds [#improve-builds]
Commit lockfiles, avoid unnecessary monorepo rebuilds, cache dependency work where supported, and keep build scripts deterministic.
Validate changes [#validate-changes]
Compare Preview deployments using the same route, data conditions, and geographic test location. Confirm that an improvement does not increase error rate, stale content, or resource usage.
# Application security guide
Easel provides platform protections, firewall rules, Attack Mode, deployment protection, managed TLS, and security telemetry. These controls complement application security; they do not replace it.
Protect non-production deployments [#protect-non-production-deployments]
Require authentication or an access policy for Preview deployments that contain unreleased features, customer data, or privileged APIs.
Do not assume an unlinked deployment URL is private.
Store secrets outside source control [#store-secrets-outside-source-control]
Use environment variables or the supported secret mechanism. Separate Preview and Production credentials, rotate exposed values, and avoid logging tokens or session data.
Restrict application access [#restrict-application-access]
Implement authentication and authorization in the application. A firewall can block traffic patterns, but it cannot determine whether a signed-in user may access a specific business object.
Use narrow firewall rules [#use-narrow-firewall-rules]
Start with logging when possible, inspect matched traffic, and then enforce. Avoid broad IP or user-agent rules that can block legitimate users or be trivially bypassed.
Protect sensitive endpoints [#protect-sensitive-endpoints]
Apply stricter controls to login, password reset, account recovery, administrative APIs, uploads, and expensive mutations. Use rate limiting when available and application-level quotas where identity-aware enforcement is required.
Validate all input [#validate-all-input]
Validate request bodies, query parameters, headers, file uploads, and webhook signatures. Treat rewritten or proxied requests as untrusted input.
Secure cookies and headers [#secure-cookies-and-headers]
Use `Secure`, `HttpOnly`, and appropriate `SameSite` cookie settings. Configure CSP, HSTS, frame restrictions, and other response headers according to the application's requirements.
Review dependencies [#review-dependencies]
Keep frameworks, adapters, runtime packages, and lockfiles current. Test upgrades in Preview before promotion.
Monitor and respond [#monitor-and-respond]
Review security events and unusual error or traffic patterns. Keep a rollback plan, credential-rotation procedure, and contact path for reporting vulnerabilities.
See [Shared responsibility](/docs/security/shared-responsibility) for the division between Easel and application responsibilities.
# Migrate from another platform
Use this guide when the source platform does not have a dedicated migration
page.
Separate application behavior from platform behavior [#separate-application-behavior-from-platform-behavior]
Identify what belongs to:
* Application source and framework
* Build system and runtime
* CDN, domain, and TLS
* Security controls
* Managed services
* Observability
* Deployment automation
Application code may transfer unchanged while platform-specific services require
replacement.
Record the current build [#record-the-current-build]
Document:
```text
Source repository
Root directory
Install command
Build command
Output directory
Runtime version
Environment variables
Generated artifacts
```
Record runtime dependencies [#record-runtime-dependencies]
Inventory:
* Functions and containers
* Persistent processes
* WebSockets and streaming
* Background jobs, queues, and scheduled work
* Local filesystem use and persistent disks
* Native binaries
* Region and private-network requirements
WebSockets are not supported on Easel today for typical framework deployments.
Plan replacements before cutover when the application depends on them.
Record delivery behavior [#record-delivery-behavior]
Inventory CDN caching, invalidation, redirects, rewrites, headers, compression,
image optimization, static assets, custom error pages, domain routing, and TLS.
Record managed services [#record-managed-services]
Identify dependencies such as database, object storage, key-value store, message
queue, authentication, email, analytics, feature flags, and secret managers.
Decide whether each service remains external or needs replacement. Easel does
not replace those managed data services as part of a deploy.
Import and validate [#import-and-validate]
1. Import the GitHub repository into Easel (or deploy with the [CLI](/docs/cli)).
2. Recreate build settings and environment variables.
3. Use a non-production Easel URL until the
[Production validation checklist](/docs/migration/production-checklist)
passes.
Cut over [#cut-over]
Follow [Domain cutover](/docs/migration/domain-cutover) and prepare
[Migration rollback](/docs/migration/rollback) before changing traffic.
Related guides [#related-guides]
* [Migration overview](/docs/migration)
* [Getting started](/docs/getting-started)
* [Framework guides](/docs/framework-guides)
* [Functions](/docs/functions)
* [CDN](/docs/cdn)
# Domain cutover
A domain cutover changes where public DNS sends requests.
Prepare the Easel deployment and rollback path before changing traffic.
Before the cutover [#before-the-cutover]
Confirm:
* [Production validation](/docs/migration/production-checklist) is complete
* The expected Easel Production deployment is Ready and Current
* The previous platform remains available
* Existing DNS values are recorded
* Relevant TTLs were lowered in advance
* The domain is added in Easel
* Mail and verification records are preserved
* Monitoring is active
* Rollback criteria are agreed
See [Migrate a domain to Easel](/docs/domains/migrate) for detailed DNS guidance.
Define rollback criteria [#define-rollback-criteria]
Examples include:
* Sustained 5xx rate above an agreed threshold
* Authentication unavailable
* Database writes failing
* Critical webhook failures
* TLS errors
* Severe latency regression
Use application-specific criteria rather than relying only on total request
volume.
Change DNS [#change-dns]
Update the record to the exact value shown by Easel:
| Host | Record |
| ----------------------------- | ---------------------------------------------- |
| Apex (`example.com`) | **A** records to the edge IPs in the dashboard |
| Subdomain (`www.example.com`) | **CNAME** to `cname.easelusercontent.com` |
Do not use ALIAS, ANAME, or CNAME flattening for apex verification. Do not add
AAAA unless Easel shows IPv6 values for your project.
Do not remove unrelated records such as MX, SPF, DKIM, DMARC, or service
verification TXT records.
If you use Cloudflare or another proxy, switch to DNS-only until the domain is
live on Easel. See [DNS configuration](/docs/domains/dns).
TLS [#tls]
Easel provisions certificates with Let’s Encrypt after DNS points at Easel.
First HTTPS requests can fail until the certificate is Ready. See
[TLS](/docs/domains/tls).
Verify from multiple networks [#verify-from-multiple-networks]
Check:
```bash
dig example.com A
dig www.example.com CNAME
curl -I https://example.com
```
Confirm:
* DNS reaches Easel
* HTTPS certificate is valid
* Correct project responds
* Expected deployment is Current
* Canonical redirect works
Monitor the application [#monitor-the-application]
Watch in [Observability](/docs/observability) and
[Logs](/docs/observability/logs):
* Request volume and status codes
* Error rate and latency
* Function failures
* Authentication and API writes
* Cache behavior
* Traffic still reaching the old platform
Keep the previous platform active [#keep-the-previous-platform-active]
Do not immediately remove the old domain configuration, delete the project, or
revoke credentials.
Clients may retain cached DNS answers during the transition.
Raise TTL after stabilization [#raise-ttl-after-stabilization]
Once traffic is stable and rollback is no longer likely, increase the DNS TTL to
the desired operational value.
Related guides [#related-guides]
* [Migrate a domain](/docs/domains/migrate)
* [Migration rollback](/docs/migration/rollback)
* [Instant Rollback](/docs/deployments/rollback)
# Migrate to Easel
Move an existing application to Easel while preserving the familiar Git,
Preview, and Production workflow.
Some source-platform features and configuration may need to be translated.
Choose your migration guide [#choose-your-migration-guide]
* [Migrate from Vercel](/docs/migration/vercel)
* [Migrate from Netlify](/docs/migration/netlify)
* [Migrate from another platform](/docs/migration/custom-platform)
Migration phases [#migration-phases]
A safe migration has six phases:
```text
Inventory
↓
Import
↓
Translate configuration
↓
Validate
↓
Cut over traffic
↓
Retire the old platform
```
Keep the previous platform available until the Easel deployment is stable and
the rollback window has passed.
1. Inventory the application [#1-inventory-the-application]
Record:
* Repository and framework
* Root directory, install command, build command, output directory
* Runtime version
* Environment variables (Preview and Production)
* Functions and middleware
* Redirects, rewrites, and response headers
* Image behavior
* Cache and revalidation behavior
* Scheduled or background work
* Storage and databases
* Webhooks
* Domains
* Deployment protection and firewall rules
* Log drains and observability integrations
* Monorepo path filters
* Git deployment settings
A successful build does not prove that every platform dependency has been
migrated.
2. Confirm framework support [#2-confirm-framework-support]
Review the matching [framework guide](/docs/framework-guides).
Pay particular attention to:
* Server rendering and static generation
* Streaming and middleware
* Image optimization
* Caching and revalidation
* Function limits and regions
3. Import the repository [#3-import-the-repository]
Import the same GitHub repository into Easel.
Do not change production DNS yet.
Review:
* Framework detection
* Root directory
* Build commands
* Production branch
* Preview behavior
* Environment variables
See [Getting started](/docs/getting-started).
4. Translate platform configuration [#4-translate-platform-configuration]
Platform-specific files and features may not transfer directly.
Examples include:
```text
vercel.json
netlify.toml
_redirects
_headers
Platform-specific function directories
Platform-specific runtime APIs
```
Use the source-platform migration guide to map each feature to Easel. Easel does
not automatically import Netlify or full Vercel project configuration.
5. Validate outside Production [#5-validate-outside-production]
Use the unique Easel deployment URL or a Preview URL.
Test homepage, deep links, authentication, APIs, databases, static assets,
images, redirects, cache behavior, webhooks, and error pages.
See [Production validation checklist](/docs/migration/production-checklist).
6. Prepare the domain cutover [#6-prepare-the-domain-cutover]
Before changing DNS:
* Add the domain in Easel
* Record existing DNS values
* Preserve MX, SPF, DKIM, DMARC, and verification records
* Lower the relevant TTL in advance
* Keep the previous platform active
* Define a rollback threshold
TLS certificates are issued after DNS points at Easel. See
[Domain cutover](/docs/migration/domain-cutover) and
[Migrate a domain](/docs/domains/migrate).
7. Cut over traffic [#7-cut-over-traffic]
Update the DNS record shown by Easel:
* Apex: **A** records to the edge IPs in the dashboard
* Subdomain: **CNAME** to `cname.easelusercontent.com`
Monitor error rate, latency, TLS, authentication, webhooks, and cache behavior
in [Observability](/docs/observability) and [Logs](/docs/observability/logs).
8. Roll back when necessary [#8-roll-back-when-necessary]
Restore the previous DNS record when production validation fails or error levels
exceed the agreed threshold.
DNS rollback is not instantaneous for clients that cached the new answer.
See [Migration rollback](/docs/migration/rollback).
9. Retire the previous platform [#9-retire-the-previous-platform]
After the migration is stable:
* Confirm traffic no longer reaches the previous platform
* Remove obsolete domains and redirects
* Revoke old deployment tokens
* Rotate credentials that no longer need access
* Disable old build hooks
* Archive required logs
* Cancel the old plan when appropriate
Do not delete the old project until the rollback window has passed.
Multi-application migrations [#multi-application-migrations]
For several applications, start with a representative, lower-risk service.
Run it long enough to observe normal deployments, production traffic,
operational incidents, billing, cache behavior, and at least one release or
rollback cycle. Then migrate more critical applications using the validated
process.
Related guides [#related-guides]
* [Getting started](/docs/getting-started)
* [Framework guides](/docs/framework-guides)
* [Deployments](/docs/deployments)
* [Domains](/docs/domains)
# Migrate from Netlify
Netlify and Easel both support Git-based deployments and previews, but their
deployment terminology and configuration files differ.
Easel does not automatically import `netlify.toml`, `_redirects`, or `_headers`.
Translate those settings into Easel project settings and framework-native
configuration.
Concept mapping [#concept-mapping]
| Netlify | Easel |
| -------------------------- | ----------------------------------------------------------- |
| Site | Project |
| Deploy Preview | Preview deployment |
| Branch deploy | Branch Preview |
| Production deploy | Production deployment |
| Published deploy | Current Production deployment |
| Deploy permalink | Unique deployment URL |
| Build contexts | Preview and Production environments |
| Netlify Functions | Easel Functions (after code adaptation) |
| Edge Functions | Framework middleware or function equivalent, when supported |
| Traffic Rules | Easel Firewall |
| Password or visitor access | Deployment protection (workspace sign-in) |
| Domain management | Easel Domains |
Inventory Netlify configuration [#inventory-netlify-configuration]
Review:
* `netlify.toml`, `_redirects`, `_headers`
* Build command, publish directory, base directory
* Build contexts and environment variables
* Functions and Edge Functions
* Scheduled and background functions
* Forms, Identity, Blobs, Large Media, Image CDN
* Plugins and split testing
* Traffic Rules, rate limiting, deploy protection
* Log drains and integrations
Mark every Netlify-specific capability as supported differently, requires
external replacement, not required, or unsupported.
Import the repository [#import-the-repository]
Import the GitHub repository into Easel.
Map:
```text
Netlify base directory → Easel root directory
Netlify build command → Easel build command
Netlify publish directory → framework or Easel output setting
Production branch → Easel Production branch
```
Review the matching [framework guide](/docs/framework-guides).
Translate build and routing [#translate-build-and-routing]
Move build settings to the Easel project.
Translate redirects and headers from `_redirects` / `netlify.toml` into:
* Framework routing (preferred when the framework owns the routes)
* Application redirects
* [Domain redirects](/docs/domains/redirects) when the rule is hostname-level
* [Security headers](/docs/security/security-headers) or framework header config
Validate status codes, wildcards, SPA fallbacks, and proxy-style rewrites
carefully. Behavior will not match Netlify one-for-one without testing.
Functions [#functions]
Compare Netlify Functions with [Easel Functions](/docs/functions):
* Request and response API
* Runtime and bundling
* Duration and region
* Environment variables
* Background and scheduled execution
Netlify-specific APIs require code changes or an external replacement.
Scheduled and background Netlify functions are not first-class Easel products;
use an external scheduler or queue when needed.
Edge Functions [#edge-functions]
Review every Edge Function for runtime APIs, geographic assumptions, cookies,
headers, rewrites, and streaming. Use framework middleware or Node.js functions
on Easel only after compatibility is confirmed for your stack.
Netlify Forms and Identity [#netlify-forms-and-identity]
These are application services, not ordinary deployment settings.
Replace them with application-owned forms and API routes, an external form
provider, an authentication provider, or a database-backed implementation.
Do not treat a successful static build as proof that these services were
migrated.
Observability and drains [#observability-and-drains]
Use [Observability](/docs/observability) and [Logs](/docs/observability/logs).
Customer log drains are not available yet. See
[Export](/docs/observability/export).
Validate and cut over [#validate-and-cut-over]
Complete the
[Production validation checklist](/docs/migration/production-checklist), then
follow [Domain cutover](/docs/migration/domain-cutover).
Keep the Netlify site and published deploy available until the rollback window
has passed.
# Production validation checklist
Complete this checklist before changing production DNS.
Deployment [#deployment]
* [ ] Expected source commit deployed
* [ ] Deployment environment is Production
* [ ] Deployment reached Ready
* [ ] Deployment is Current (or promotion plan is clear)
* [ ] Framework detected correctly
* [ ] Build settings match the application
* [ ] Required resources were generated
* [ ] No unexplained build warnings
Routes and rendering [#routes-and-rendering]
* [ ] Homepage
* [ ] Deep links
* [ ] Dynamic routes
* [ ] Server-rendered routes
* [ ] Static routes
* [ ] API routes
* [ ] Redirects
* [ ] Rewrites
* [ ] Custom error pages
* [ ] Not-found behavior
Authentication and sessions [#authentication-and-sessions]
* [ ] Sign in
* [ ] Sign out
* [ ] Session refresh
* [ ] Password reset
* [ ] OAuth callbacks (updated for the new hostname)
* [ ] Cookie domain and Secure cookie behavior
* [ ] CSRF protections
* [ ] Authorized and unauthorized routes
Data and integrations [#data-and-integrations]
* [ ] Database reads and writes
* [ ] Object storage and file uploads
* [ ] Email
* [ ] Webhooks
* [ ] Third-party APIs
* [ ] Queues and background work
* [ ] Scheduled work (external scheduler if used)
Delivery [#delivery]
* [ ] Static assets, images, and fonts
* [ ] Compression
* [ ] Cache headers
* [ ] Cache hits and misses (`X-Easel-Cache`)
* [ ] Revalidation
* [ ] Streaming
* [ ] Large responses
Security [#security]
* [ ] Platform protections active
* [ ] Firewall rules translated, if needed
* [ ] Attack Mode disabled unless intentionally needed
* [ ] Deployment protection correct for previews
* [ ] Security headers
* [ ] CORS
* [ ] Secrets scoped to Preview vs Production correctly
Domains [#domains]
* [ ] Apex and `www` / canonical redirect planned
* [ ] DNS records recorded
* [ ] Mail and verification records preserved
* [ ] TLS path understood (cert after DNS points to Easel)
* [ ] OAuth and webhook URLs updated
* [ ] Canonical URLs, sitemap, and robots behavior correct
Observability [#observability]
* [ ] Requests appear in **Logs**
* [ ] Function activity and Traces appear as expected
* [ ] Cache outcomes visible
* [ ] Error rate baseline recorded
* [ ] Latency / compute baseline recorded
Failure testing [#failure-testing]
* [ ] Missing route
* [ ] Application error
* [ ] Upstream timeout
* [ ] Invalid authentication
* [ ] Failed webhook signature
* [ ] Function timeout behavior
* [ ] DNS rollback procedure rehearsed
* [ ] Instant Rollback path understood for post-cutover releases
Acceptance [#acceptance]
Record:
```text
Validated deployment ID:
Validated commit:
Validator:
Date:
Known limitations:
Rollback threshold:
```
Related guides [#related-guides]
* [Domain cutover](/docs/migration/domain-cutover)
* [Migration rollback](/docs/migration/rollback)
* [Observability](/docs/observability)
# Migration rollback
A migration rollback restores the previous traffic destination.
It is different from an Easel [Instant Rollback](/docs/deployments/rollback),
which switches between deployments inside Easel without changing DNS.
Before migration [#before-migration]
Record:
* Previous DNS record type
* Previous DNS value
* Previous TTL
* Previous platform project
* Required credentials
* Validation commands
* Responsible operator
Keep the previous application and services running.
When to roll back [#when-to-roll-back]
Use the criteria established before cutover.
Typical triggers include:
* Critical application paths unavailable
* Authentication failure
* Data corruption risk
* Webhook or payment failure
* TLS failure
* Sustained error increase
* Severe performance regression
Restore DNS [#restore-dns]
Replace the Easel routing record with the recorded previous value.
Do not guess or recreate the value from memory.
Understand propagation [#understand-propagation]
Some users may continue reaching Easel until their cached DNS answer expires.
During rollback:
* Keep both platforms operational
* Monitor traffic on both
* Avoid destructive configuration changes
* Communicate partial recovery accurately
Verify recovery [#verify-recovery]
Confirm:
* DNS resolves to the previous platform
* HTTPS works
* Authentication works
* Critical writes work
* Webhooks succeed
* Error rate returns to baseline
* Traffic decreases on Easel
Preserve evidence [#preserve-evidence]
Keep:
* Easel deployment ID
* Request IDs and Trace links
* Logs and error screenshots
* DNS timestamps
* Monitoring data
Do not delete the Easel project while investigating.
Prepare the next attempt [#prepare-the-next-attempt]
Before another cutover:
1. Identify the failure.
2. Reproduce it outside Production.
3. Correct the application or configuration.
4. Repeat the [Production validation checklist](/docs/migration/production-checklist).
5. Confirm rollback readiness again.
Related guides [#related-guides]
* [Domain cutover](/docs/migration/domain-cutover)
* [Instant Rollback](/docs/deployments/rollback)
* [Observability troubleshooting](/docs/observability/troubleshooting)
# Migrate from Vercel
Vercel and Easel share a Git-based Preview and Production workflow, but not
every platform feature has identical semantics.
Concept mapping [#concept-mapping]
| Vercel | Easel |
| ----------------------------- | -------------------------------------------- |
| Project | Project |
| Preview deployment | Preview deployment |
| Production deployment | Production deployment |
| Current production deployment | Current Production deployment |
| Generated deployment URL | Unique deployment URL |
| Branch URL | Branch Preview URL |
| Environment variables | Environment variables (Preview / Production) |
| Functions | Easel Functions |
| Firewall | Easel Firewall |
| Attack Challenge Mode | Attack Mode |
| Observability | Observability, Logs, Invocations, Traces |
| Domains | Easel Domains |
| Deployment Protection | Deployment protection (workspace sign-in) |
Inventory Vercel configuration [#inventory-vercel-configuration]
Review:
* Framework preset, root directory, install and build commands
* Node.js version and Production branch
* Environment variables
* `vercel.json` and framework-native redirects, rewrites, and headers
* Functions and middleware
* ISR and revalidation
* Data Cache / Runtime Cache usage
* Image optimization
* Cron jobs
* Blob, KV, Postgres, or other managed storage
* Firewall rules and deployment protection
* Log drains, Web Analytics, or Speed Insights
* Build and function limits
Import the repository [#import-the-repository]
Import the GitHub repository into Easel and compare detected settings with the
Vercel project.
Do not assume matching framework detection means matching runtime behavior.
Review the matching [framework guide](/docs/framework-guides).
Translate configuration [#translate-configuration]
Build settings [#build-settings]
Map install command, build command, root directory, and Production branch into
Easel project settings.
Redirects, rewrites, and headers [#redirects-rewrites-and-headers]
Prefer framework-native configuration where possible (for example `next.config`
for Next.js). For Vite-style static apps, `vercel.json` redirects, rewrites, and
headers may apply—see the [Vite guide](/docs/framework-guides/vite).
Do not copy unsupported `vercel.json` fields without verifying their effect.
Cron schedules in `vercel.json` are not a first-class Easel product today.
Environment variables [#environment-variables]
Create Preview and Production values in
**Project settings → Environment Variables**.
Check:
* Build-time versus runtime values
* Public variable prefixes
* Preview branch overrides
* Whether redeployments need new snapshots after secret changes
Deployments snapshot variables at create time. See
[Deployment environments](/docs/deployments/environments) and
[Secrets](/docs/security/secrets).
Functions and middleware [#functions-and-middleware]
Compare runtime, duration, streaming, `after` / `waitUntil` behavior, and
filesystem assumptions with [Functions](/docs/functions) and your framework
guide.
Easel Functions run in US East (`iad`) today. See
[Function regions](/docs/functions/regions) and
[Function limits](/docs/functions/limits).
Caching and revalidation [#caching-and-revalidation]
Inventory static assets, CDN cache headers, ISR, revalidation APIs, and Runtime
Cache usage.
Validate with [Caching](/docs/cdn/caching),
[Revalidation](/docs/cdn/revalidation),
[Runtime Cache](/docs/runtime-cache), and
[Cache observability](/docs/observability/cache).
Images [#images]
For Next.js, `next/image` can use Easel image optimization. Test remote
allowlists, formats, and cache behavior after deploy.
Cron and background work [#cron-and-background-work]
Easel does not provide a first-class cron product today. Move scheduled work to:
* An external scheduler calling a protected HTTP route
* A queue or workflow system
* A separate service
Background work that continues after the response should use framework
`after` / `waitUntil` patterns within function duration limits—not unbounded
platform lifetime.
Firewall and Attack Mode [#firewall-and-attack-mode]
Recreate only the controls the application needs:
* [Custom firewall rules](/docs/security/custom-rules)
* [Attack Mode](/docs/security/attack-mode)
* [Deployment protection](/docs/security/deployment-protection)
Attack Mode is an emergency traffic control, not application authentication.
Observability [#observability]
After importing:
1. Generate representative requests.
2. Confirm records in **Logs**.
3. Inspect Traces, cold starts, and Invocations.
4. Validate cache outcomes.
Customer log drains and OTLP export sinks are not available yet. See
[Export observability data](/docs/observability/export).
Validate and cut over [#validate-and-cut-over]
Complete the
[Production validation checklist](/docs/migration/production-checklist), then
follow [Domain cutover](/docs/migration/domain-cutover).
Keep the Vercel project active until the rollback window has passed.
# Cache observability
Cache observability explains whether Easel served a response from cache or
performed additional work.
Cache outcomes [#cache-outcomes]
Easel exposes cache processing through the `X-Easel-Cache` response header and
related Logs filters.
| Status | Meaning |
| ---------- | ---------------------------------------------------------------------------------------------------------------------- |
| **HIT** | A fresh cached response was served |
| **STALE** | A stale cached response was served within an explicit stale-while-revalidate window while refreshing in the background |
| **MISS** | No usable fresh or SWR-eligible stale entry was found; origin or regeneration ran |
| **BYPASS** | The request or response was not eligible for shared caching |
| **ERROR** | Cache processing encountered an error path |
Treat `X-Easel-Cache` as authoritative for whether Easel reused a cached
response. See [Caching](/docs/cdn/caching) and
[CDN headers](/docs/cdn/headers).
Definitions [#definitions]
HIT [#hit]
The response was served from cache without invoking the application origin or
function for that response body.
MISS [#miss]
No usable cached response existed, so Easel fetched or generated one.
BYPASS [#bypass]
The request did not use shared cache because of request properties, response
headers, or policy (for example `Authorization`, `Set-Cookie`, `private`, or
missing shared TTL).
STALE [#stale]
A stale entry was eligible under `stale-while-revalidate` and was served while
Easel refreshed in the background.
Security and cache [#security-and-cache]
Security controls run before cache lookup. A blocked or challenged request does
not proceed to ordinary application cache serving. See
[Security evaluation order](/docs/security/request-chain).
Runtime Cache panel [#runtime-cache-panel]
On Observability, the Runtime Cache panel summarizes project-scoped runtime
cache operations such as reads, hits, misses, writes, revalidations, and
evictions for frameworks that use Easel’s runtime cache APIs.
See [Runtime Cache](/docs/runtime-cache).
Debugging workflow [#debugging-workflow]
1. Reproduce the request and read `X-Easel-Cache`.
2. Confirm cache headers on the origin response (`Cache-Control`, cookies).
3. Filter **Logs** by cache status when available.
4. For ISR or runtime-cache issues, check revalidation docs and the Runtime
Cache panel.
Related guides [#related-guides]
* [Caching](/docs/cdn/caching)
* [Revalidation](/docs/cdn/revalidation)
* [CDN troubleshooting](/docs/cdn/troubleshooting)
* [Request analytics](/docs/observability/requests)
# Deployment events
Deployment activity explains how application versions move from source to
production traffic. Most deployment lifecycle detail lives in **Deployments**,
not inside Observability charts.
Use Observability to measure what happened **after** a deployment became Ready.
What to inspect in Deployments [#what-to-inspect-in-deployments]
From the project **Deployments** view (and CLI inspect), you can typically see:
* Deployment created and status transitions
* Build logs and failure reasons
* Environment (`preview` or `production`)
* Source commit and branch
* Promotion and Instant Rollback actions
* Which deployment is Current for production domains
See [Deployments](/docs/deployments), [Promote](/docs/deployments/promote), and
[Rollback](/docs/deployments/rollback).
Correlate with Observability [#correlate-with-observability]
After a release:
1. Note the deployment ID and Ready timestamp.
2. Open **Observability** for a window that starts at that time.
3. Watch error rate, compute, cold starts, and bandwidth.
4. Filter **Logs** by deployment ID when investigating a regression.
5. Open request Traces for slow or failing examples.
Observability does not currently draw automatic deployment markers on charts.
Use the deployment timestamp and filters instead.
Configuration changes [#configuration-changes]
Firewall rules, Attack Mode, and deployment protection can change traffic shape
without a new deployment. When investigating a sudden block or challenge spike:
* Check **Project settings** security controls
* Review [Security events](/docs/observability/security)
* Confirm the change time against the Observability window
Environment variable changes apply to **new** deployments via snapshots. See
[Secrets](/docs/security/secrets) and
[Environments](/docs/deployments/environments).
Related guides [#related-guides]
* [Request analytics](/docs/observability/requests)
* [Deployments overview](/docs/deployments)
* [CLI deployments](/docs/cli/deployments)
# Export observability data
Use the dashboard and CLI to inspect and retrieve observability data for
operations and debugging.
Dashboard access [#dashboard-access]
* **Observability**: charts and custom queries
* **Logs**: request list, detail, log lines, and Traces
* **Invocations**: wake-level metrics and request waterfalls
Copy request IDs, invocation IDs, and deployment IDs from these views when
filing support tickets or correlating with application logs.
CLI access [#cli-access]
Query the same request stream from the terminal:
```bash
easel logs --since 1h --status-code 5xx
easel logs --request-id --expand
easel logs --follow --timeout 10m
```
See [Query request logs](/docs/cli/logs).
What is not available yet [#what-is-not-available-yet]
The following export destinations are not customer-facing product features
today:
* Log drains to external HTTPS endpoints
* Customer-managed OTLP export sinks
* Metrics export to third-party monitoring
* Observability webhooks
* Object-storage archives or SIEM connectors
OpenTelemetry spans are collected **into** Easel Traces. See
[OpenTelemetry](/docs/observability/opentelemetry).
If you need longer retention or external analysis, export selected request IDs
and summaries manually, or retain application-level logs in your own systems.
Related guides [#related-guides]
* [Logs](/docs/observability/logs)
* [Retention and limits](/docs/observability/limits)
* [Tracing](/docs/observability/tracing)
# Function observability
Function observability explains how Easel executes server-side code for a
deployment.
Use **Observability** charts for trends, **Logs** for per-request compute
fields, and **Invocations** when one function wake served multiple HTTP
requests.
Invocations [#invocations]
One function invocation (wake) can serve more than one HTTP request when the
runtime keeps the isolate warm and multiplexes traffic.
**Invocations** lists those wakes with columns such as:
* Route
* Request count (**Reqs**)
* Cold start
* Duration
* Compute
* AWS duration and AWS billed
* Init
* Memory
* Instance
Select an invocation to open:
* **Overview**: summary metrics and a waterfall of requests served on that wake
* **Trace**: an invocation-level Trace focused on lifecycle and per-request
summary bars
Use **Open in Logs** to jump to the request list for the same invocation ID.
Duration fields [#duration-fields]
Different duration values measure different things:
| Field | Meaning |
| -------------------------- | ---------------------------------------------------------- |
| **Duration** (Invocations) | Wall time for the wake |
| **Compute duration** | Customer function work through response body completion |
| **Post-response** | Work after the response finishes (`waitUntil`, flush) |
| **AWS duration** | Duration reported by the Lambda Telemetry API for the wake |
| **AWS billed** | Billed duration reported for the wake |
| **AWS init** / **Init** | Initialization time when the wake was cold |
Do not use “duration” without checking which field you mean. Request Trace spans
show where time went inside one HTTP request; AWS billed and cold start remain
on request detail and Invocations.
Cold and warm starts [#cold-and-warm-starts]
* **Cold**: the wake initialized a new runtime process.
* **Warm**: the wake reused an existing process.
Observability **Function Starts** charts break volume into cold and warm.
Easel does not use a separate “hot” product term.
Memory and instance [#memory-and-instance]
Invocations can show configured memory and maximum memory used for the wake, plus
an **Instance** identifier for the underlying compute process.
Function region for compute is typically `iad` (US East). See
[Function regions](/docs/functions/regions).
Errors and timeouts [#errors-and-timeouts]
Failed requests appear with 5xx statuses in Logs and error series on
Observability charts. Investigate with request detail, function log lines, and
Trace spans.
Application timeouts follow your route `maxDuration` and platform limits. See
[Function limits](/docs/functions/limits).
Related guides [#related-guides]
* [Request details](/docs/observability/request-details)
* [Tracing](/docs/observability/tracing)
* [Functions overview](/docs/functions)
* [Function runtime](/docs/functions/runtime)
# Observability
Easel observability connects each incoming request to the deployment, route,
cache decision, function execution, and security action that handled it.
Use observability to answer questions such as:
* Which deployment served this request?
* Did the response come from cache?
* Which route matched?
* Did a function run?
* Was the function cold or warm?
* Did a firewall rule block or challenge it?
* Where did the request spend time?
* Did the failure happen during build, routing, or runtime?
Surfaces [#surfaces]
Open a project and use these dashboard views:
| Surface | Use it for |
| ----------------- | -------------------------------------------------------------------------- |
| **Observability** | Traffic, bandwidth, function starts, compute, and custom queries over time |
| **Logs** | Individual requests, function log lines, and per-request Traces |
| **Invocations** | Multiplexed function wakes, cold starts, and AWS billing fields |
From the terminal, use [`easel logs`](/docs/cli/logs) to query and follow the
same request stream.
Observability model [#observability-model]
Easel organizes observability around related data types:
* **Requests** describe an incoming HTTP request and its final response.
* **Logs** contain application and platform-generated messages for a request.
* **Metrics** aggregate behavior over time on Observability charts.
* **Traces** connect edge routing, function work, and application OpenTelemetry
spans for one request.
* **Invocations** describe a function wake that may serve multiple requests.
* **Security signals** explain firewall and access-control decisions when
available.
* **Deployment activity** lives primarily in Deployments and build logs, with
filters that let you scope Observability to a deployment.
These signals share stable identifiers such as request ID and invocation ID so
you can move from a chart to an individual request and then to its Trace.
Request lifecycle [#request-lifecycle]
A request may pass through several stages:
```text
Client request
↓
Security evaluation
↓
Domain and deployment routing
↓
Cache lookup
↓
Static response, middleware, or function
↓
Response
```
Security controls run before cache and application execution. See
[Security evaluation order](/docs/security/request-chain).
Start here [#start-here]
* [Request analytics](/docs/observability/requests)
* [Request details](/docs/observability/request-details)
* [Logs](/docs/observability/logs)
* [Function observability](/docs/observability/functions)
* [Cache observability](/docs/observability/cache)
* [Metrics](/docs/observability/metrics)
* [Tracing](/docs/observability/tracing)
* [OpenTelemetry](/docs/observability/opentelemetry)
* [Security events](/docs/observability/security)
* [Deployment events](/docs/observability/deployments)
* [Export](/docs/observability/export)
* [Retention and limits](/docs/observability/limits)
* [Troubleshooting](/docs/observability/troubleshooting)
Related documentation [#related-documentation]
* [Query request logs (CLI)](/docs/cli/logs)
* [CDN headers](/docs/cdn/headers)
* [Firewall observability](/docs/security/firewall-observability)
* [Functions](/docs/functions)
# Observability retention
These limits describe current dashboard, CLI, and runtime capture behavior for
observability signals. For platform-wide ceilings, see
[Limits reference](/docs/reference/limits).
Dashboard time windows [#dashboard-time-windows]
Typical presets:
| Surface | Windows |
| -------------------- | ---------------------------------- |
| Observability charts | 6h, 12h, 24h, 7d |
| Logs | From about 30 minutes up to 7 days |
Metric buckets are commonly 5 minutes (≤24h windows) or 60 minutes (longer
windows).
Longer archival retention is not published as a separate product SLA today.
Request list [#request-list]
Logs queries return a bounded number of rows per page or request (commonly up to
a few hundred). Narrow the time range and filters when searching busy projects.
Function log capture [#function-log-capture]
Per-invoke console capture is bounded so telemetry cannot keep the runtime open
indefinitely. Approximate platform limits:
| Limit | Value |
| ------------------------ | ------- |
| Max lines per invoke | 256 |
| Max bytes per line | 256 KiB |
| Max total captured bytes | 1 MiB |
Excess output may be dropped. Prefer concise structured logs on hot paths.
OpenTelemetry span capture [#opentelemetry-span-capture]
Application span buffers are bounded by count and size. Excess spans may be
truncated on the Trace. See [OpenTelemetry](/docs/observability/opentelemetry).
CLI follow [#cli-follow]
`easel logs --follow` polls periodically (about every 10 seconds) and respects
`--timeout` (default 5 minutes unless you set another value).
Delivery [#delivery]
Observability shipping is best-effort and must not block request handling. Do
not treat Logs as a guaranteed, complete audit log for compliance without an
external retention system.
Related guides [#related-guides]
* [Logs](/docs/observability/logs)
* [Metrics](/docs/observability/metrics)
* [Export](/docs/observability/export)
* [Troubleshooting](/docs/observability/troubleshooting)
# Logs
Logs provide detailed messages from functions, application code, and selected
platform components, correlated to individual requests.
Where logs appear [#where-logs-appear]
* **Logs** in the project dashboard: request list, detail panel, and dock
* [`easel logs`](/docs/cli/logs) in the terminal
Build output lives with the deployment (inspect build logs from Deployments or
the CLI). Request Logs focus on runtime traffic after a deployment is serving
requests.
Request list and filters [#request-list-and-filters]
**Logs** lists recent requests for the project. Filter by:
* Time range
* Environment
* Method
* Status
* Path and route
* Host
* Cache status
* Console level (`warning`, `error`, `fatal`)
* Deployment ID
Select a row to open detail. The dock **Logs** tab shows function and platform
log lines for that request.
Application logs [#application-logs]
Write to standard console APIs in your function runtime. Easel captures console
output and associates it with the request ID when available.
Prefer structured JSON when you need searchable fields:
```json
{
"level": "info",
"message": "Checkout completed",
"order_id": "ord_123"
}
```
Do not log secrets, tokens, or full connection strings. Automatic redaction
cannot catch every transformed value. See [Secrets](/docs/security/secrets).
Correlation fields [#correlation-fields]
Useful identifiers:
| Field | Use |
| ------------------------- | -------------------------------------------------- |
| Request ID (`X-Easel-Id`) | One HTTP request across Logs, Trace, and support |
| Invocation ID | The function wake that may serve multiple requests |
| Deployment ID | Scope to a specific deployment |
| Environment | `production` or `preview` |
From an Invocation, use **Open in Logs** or filter with `invocationId:…`.
CLI [#cli]
```bash
easel logs
easel logs --follow --expand --timeout 10m
easel logs --environment production --status-code 5xx --since 1h
easel logs --request-id
```
`--follow` polls for new requests. `--expand` prints function log lines for each
request.
See [Query request logs](/docs/cli/logs) for the full option list.
Capture limits [#capture-limits]
Function log capture is bounded per invoke so telemetry cannot keep the runtime
open indefinitely. Very chatty processes may drop excess lines. Prefer concise,
structured messages for high-volume paths.
Delivery is best-effort and must not block the request path. Do not treat Logs
as a guaranteed audit archive.
Related guides [#related-guides]
* [Request details](/docs/observability/request-details)
* [Tracing](/docs/observability/tracing)
* [Function observability](/docs/observability/functions)
* [Query request logs (CLI)](/docs/cli/logs)
# Metrics
Metrics summarize application and platform behavior over time on the project
**Observability** page.
Default charts [#default-charts]
Typical charts include:
Traffic [#traffic]
* **Edge Requests**: request volume and error rates
* **Edge Bandwidth**: incoming and outgoing bytes
Functions [#functions]
* **Function Starts**: cold versus warm starts
* **Functions**: invocation and error series
* **Compute**: total compute duration
Runtime Cache [#runtime-cache]
* Runtime Cache operations when the project uses runtime cache APIs
Time windows and buckets [#time-windows-and-buckets]
Select a preset window such as 6 hours, 12 hours, 24 hours, or 7 days.
Aggregation buckets are typically:
* 5 minutes for windows up to 24 hours
* 60 minutes for longer windows
Custom queries [#custom-queries]
Open **Observability → Query** (or the project query view) to build charts from
supported metrics such as:
* Edge requests
* Duration
* Bandwidth / FDT fields
* Route cache and route bandwidth
* Function metrics
Supported aggregations include count, sum, min, max, average, and percentiles
such as p75, p90, p95, and p99 where the metric allows them.
Custom query metrics are platform-defined fields and aggregations, not arbitrary
customer-defined metric names emitted from application code.
How to use metrics after a deploy [#how-to-use-metrics-after-a-deploy]
1. Open Observability for the hours after the release.
2. Compare error rate, latency/compute, cold starts, and bandwidth to the prior
window.
3. When a series moves, open **Logs** for the same time range.
4. Inspect request detail and Trace for examples.
Deployment overlay markers on charts are not a separate product feature today.
Use time range and deployment ID filters instead.
Related guides [#related-guides]
* [Request analytics](/docs/observability/requests)
* [Function observability](/docs/observability/functions)
* [Cache observability](/docs/observability/cache)
* [Retention and limits](/docs/observability/limits)
# OpenTelemetry
Easel collects OpenTelemetry spans emitted from your function runtime and nests
them under the platform **Invoke function** span in the request Trace.
Use OpenTelemetry to see database queries, outbound fetches, and application
operations next to edge routing and invoke timing.
How collection works [#how-collection-works]
On supported Node.js runtimes, Easel provides a request context compatible with
`@vercel/otel` and `telemetry.reportSpans`. Spans buffered during the invoke are
flushed into the observability pipeline and attached to the request Trace.
You do not configure a separate OTLP endpoint for Easel collection. Instrument
your app; Easel ingests the spans with the request.
Span capture is bounded (count and byte limits). Excess spans may be truncated.
Next.js [#nextjs]
Create `instrumentation.ts` in the project root or `src` directory:
```ts
export async function register() {
if (process.env.NEXT_RUNTIME === "nodejs") {
await import("./instrumentation.node");
}
}
```
In `instrumentation.node.ts`, initialize `@vercel/otel` or a standard
OpenTelemetry Node SDK and instrumentation packages for the libraries you use.
See the [Next.js framework guide](/docs/framework-guides/nextjs).
Other Node.js frameworks [#other-nodejs-frameworks]
For React Router, TanStack Start, and other Node.js server runtimes on Easel
Functions:
1. Install OpenTelemetry SDK and instrumentation packages.
2. Register instrumentation at process startup for the server entry.
3. Instrument server routes, loaders, database clients, and outbound HTTP.
4. Deploy and open **Logs → Trace** for a request that hit the instrumented path.
Framework-specific notes live in each [framework guide](/docs/framework-guides).
What you will see [#what-you-will-see]
After instrumentation:
1. Open **Logs** and select a request.
2. Open the **Trace** tab.
3. Expand **Invoke function**.
4. Inspect Framework, Fetch, and Custom spans from your application.
If instrumentation is missing, platform spans still appear (Resolve Deployment,
Resolve Route, Invoke middleware, Invoke function).
Limits [#limits]
* Collection is for Easel Traces, not a general-purpose customer OTLP sink.
* Spans are associated with the active request and invocation when available.
* Late async work should finish within `waitUntil` bounds so spans can flush
before the isolate parks. See [Function runtime](/docs/functions/runtime).
Related guides [#related-guides]
* [Tracing](/docs/observability/tracing)
* [Request details](/docs/observability/request-details)
* [Next.js on Easel](/docs/framework-guides/nextjs)
# Request details
The request detail view connects one client request to the deployment, route,
cache decision, function work, and logs that handled it.
Request identity [#request-identity]
Each request has a stable **request ID**. Easel also returns it to clients as
`X-Easel-Id`.
Use the request ID to:
* Search Logs and the CLI (`easel logs --request-id …`)
* Correlate function log lines and Trace spans
* Contact support
* Jump between related views
The request ID is a UUID string generated at the edge.
Open a request [#open-a-request]
1. Open the project and go to **Logs**.
2. Filter to the time range and path you care about.
3. Select a request row.
4. Review the detail panel.
5. Use the dock tabs **Logs** and **Trace**.
From detail you can also open the matching invocation when one exists.
Summary fields [#summary-fields]
A request summary commonly includes:
* Request ID
* Timestamp (request started)
* Host
* Method and path
* Status code
* User agent and referer when available
* Firewall badge when a security action is present
* Function and middleware indicators when compute ran
Timing and function fields [#timing-and-function-fields]
When a function handled the request, the detail panel can show:
| Field | Meaning |
| -------------------- | ---------------------------------------------------------------------- |
| **Compute duration** | Time executing customer function code through response body completion |
| **Post-response** | Work after the response finishes (for example `waitUntil` / flush) |
| **AWS duration** | Lambda-reported duration for the wake |
| **AWS billed** | Lambda-reported billed duration for the wake |
| **AWS init** | Initialization time when the wake was a cold start |
| **Cold start** | Whether this invoke initialized a new runtime process |
| **Invocation ID** | AWS request ID for the function wake |
| **Instance** | Lambda instance identity for the wake |
AWS duration, billed duration, and init apply to the **invocation** (the wake),
not always as independent per-HTTP-request meters. Use Invocations when one wake
served multiple requests.
These fields sit on the detail panel. They are not separate Trace span names.
Dock: Logs and Trace [#dock-logs-and-trace]
The sticky dock under the list has two tabs for the selected request:
* **Logs**: function and platform log lines for that request
* **Trace**: the span tree for edge and function work on that request
See [Logs](/docs/observability/logs) and [Tracing](/docs/observability/tracing).
What detail does not replace [#what-detail-does-not-replace]
* Cold start and AWS billed context also appear on **Invocations**.
* Build failures appear in deployment build logs, not request detail.
* Cache policy diagnosis often needs the `X-Easel-Cache` response header in
addition to Logs filters. See [Cache observability](/docs/observability/cache).
Related guides [#related-guides]
* [Logs](/docs/observability/logs)
* [Function observability](/docs/observability/functions)
* [Tracing](/docs/observability/tracing)
* [Query request logs (CLI)](/docs/cli/logs)
# Request analytics
Request analytics summarizes traffic handled by an Easel project.
Use it to understand:
* Request volume
* Response status and error rate
* Latency and compute
* Cache effectiveness
* Function starts (cold vs warm)
* Bandwidth
* Deployment-scoped activity
Where to look [#where-to-look]
1. Open the project.
2. Open **Observability** for charts over a time window.
3. Open **Logs** for the request list behind a spike.
4. Select a request to open detail, log lines, and Trace.
Typical Observability charts include:
* **Edge Requests**: request volume and error rates at the edge
* **Edge Bandwidth**: bytes served (incoming and outgoing)
* **Function Starts**: cold versus warm starts
* **Functions** and **Compute**: invocations, errors, and duration
Pick a deploy window and compare it to the hours before the release. When a
chart moves, use Logs or Invocations to inspect the requests behind the spike.
Filters [#filters]
In **Logs**, useful filters include:
* Time range (for example 30 minutes to 7 days)
* Environment (`production` or `preview`)
* Method
* Status
* Path and route
* Host
* Cache status
* Console level
* Deployment ID
Use `invocationId:…` style filters when jumping from an Invocation to its
requests.
From charts to requests [#from-charts-to-requests]
A practical workflow:
1. Confirm the time window and environment on Observability.
2. Note which chart moved (errors, bandwidth, cold starts, compute).
3. Open **Logs** for the same window.
4. Filter to the failing status, path, or deployment.
5. Open a request for detail and Trace.
Related guides [#related-guides]
* [Request details](/docs/observability/request-details)
* [Metrics](/docs/observability/metrics)
* [Logs](/docs/observability/logs)
* [Function observability](/docs/observability/functions)
# Security events
Security events explain why Easel allowed, blocked, logged, or challenged a
request.
For the full security product model, see
[Firewall observability](/docs/security/firewall-observability).
Where security shows up [#where-security-shows-up]
* Request detail **Firewall** badge on Logs
* Project overview firewall action snapshots
* Observability charts that group by firewall action when the field is present
* Response headers such as `X-Easel-Firewall-Action` and
`X-Easel-Firewall-Rule-Id` on some denials
Actions [#actions]
Customer-facing action values you may see include:
```text
deny
challenge
challenge_pass
challenge_fail
redirect
log
bypass
```
Platform protections may also surface actions such as `ban` or `throttle`.
Decision sources [#decision-sources]
Prefer product concepts when describing a decision:
* Platform protection
* Custom rule
* Attack Mode
* Deployment protection
See [Attack Mode](/docs/security/attack-mode) and
[Custom firewall rules](/docs/security/custom-rules).
Debugging workflow [#debugging-workflow]
1. Reproduce the request and capture the request ID.
2. Open **Logs** for that ID or time window.
3. Check the Firewall badge and status code.
4. Confirm rule configuration in **Project settings → Custom WAF rules**.
5. Confirm whether Attack Mode or deployment protection is enabled.
When a challenge interstitial appears, verification outcomes may show as
challenge pass or fail around `/.well-known/easel-challenge/verify`.
Related guides [#related-guides]
* [Firewall observability](/docs/security/firewall-observability)
* [Security troubleshooting](/docs/security/troubleshooting)
* [Request details](/docs/observability/request-details)
# Tracing
A request Trace is a span tree for one HTTP request. Easel builds it from
platform timing plus any OpenTelemetry (OTEL) spans your function emits.
How to open a Trace [#how-to-open-a-trace]
1. Open the project and go to **Logs**.
2. Filter to the time range and path you care about.
3. Select a request row.
4. Open the **Trace** tab in the dock.
5. Choose **Timeline**, **Tree**, or **Waterfall**.
From Logs detail you can also open the matching invocation when you need the
function-level view.
Platform spans [#platform-spans]
Platform spans include:
* Root span for the request method and path
* **Resolve Deployment** and **Resolve Route** for edge routing
* **Invoke middleware** and **Invoke function** for compute windows
* Nested application OTEL spans under **Invoke function** when you instrument
the runtime
If the function has not emitted OTEL yet, the Trace still shows platform spans.
A placeholder under the invoke notes that application spans appear there once
instrumentation is present.
Timeline, Tree, and Waterfall [#timeline-tree-and-waterfall]
The Trace toolbar shares one span tree across three views:
* **Timeline**: absolute-time lanes with zoom and a minimap
* **Tree**: hierarchy with expand and collapse
* **Waterfall**: indented labels with duration bars
Search spans from the Trace toolbar when the tree is large. Span kinds in the UI
include Platform, Framework, Fetch, and Custom.
What a Trace does not replace [#what-a-trace-does-not-replace]
Cold start flags and **AWS billed** duration remain on the request detail panel
and on **Invocations**. Use them together with the Trace:
* The Trace shows where time went inside the request
* Detail and Invocations show billing and cold-start context for the wake
OpenTelemetry [#opentelemetry]
Instrument your Node.js function with OpenTelemetry so application spans nest
under **Invoke function**. See
[OpenTelemetry](/docs/observability/opentelemetry).
Easel collects spans into the request Trace. Customer-managed OTLP export to an
external backend is not a separate product feature today.
Invocation Traces [#invocation-traces]
**Invocations** can show an invocation-level Trace focused on wake lifecycle and
per-request summary bars when one wake served multiple requests.
Related guides [#related-guides]
* [Request details](/docs/observability/request-details)
* [OpenTelemetry](/docs/observability/opentelemetry)
* [Function observability](/docs/observability/functions)
* [Logs](/docs/observability/logs)
# Observability troubleshooting
Start with a request ID, deployment ID, invocation ID, or exact timestamp
whenever possible.
A request does not appear [#a-request-does-not-appear]
Check:
* Selected time range
* Project and environment filters
* Deployment ID
* Domain or host filter
* Whether the request hit a different project
* Brief ingest delay after the request completed
Very early platform-only traffic without project attribution may not appear in
project Logs.
Logs are missing [#logs-are-missing]
Check:
* The function actually ran (cache HIT and static responses produce little or no
function output)
* The selected deployment and environment
* Console level filters
* Whether capture limits dropped excess lines
* Whether the process exited before flush on a crash path
Traces look empty under Invoke function [#traces-look-empty-under-invoke-function]
Platform spans still appear without application instrumentation. To see nested
app spans:
1. Confirm OpenTelemetry registration in the runtime.
2. Deploy the instrumented build.
3. Hit a path that exercises the instrumented code.
4. Re-open **Logs → Trace**.
See [OpenTelemetry](/docs/observability/opentelemetry).
AWS billed or init fields are empty [#aws-billed-or-init-fields-are-empty]
AWS duration, billed duration, and init come from the function wake telemetry
report. They attach to the **invocation** and can arrive slightly after the HTTP
response completes. Open **Invocations** for the wake, or refresh request detail
after a short delay.
Cache status disagrees with expectations [#cache-status-disagrees-with-expectations]
1. Read `X-Easel-Cache` on the live response.
2. Confirm `Cache-Control` and cookies on the origin response.
3. See [Cache observability](/docs/observability/cache) and
[CDN troubleshooting](/docs/cdn/troubleshooting).
Firewall badge is Allow but the client saw a challenge [#firewall-badge-is-allow-but-the-client-saw-a-challenge]
Challenge and platform decisions can short-circuit before ordinary application
handling. Confirm Attack Mode and custom rules in project settings, and see
[Security events](/docs/observability/security).
Metrics and Logs disagree slightly [#metrics-and-logs-disagree-slightly]
Charts aggregate over buckets; Logs lists individual requests. Align the time
window, environment, and deployment filters. Expect brief ingest delay and
best-effort delivery.
Information to include with support [#information-to-include-with-support]
Include:
* Workspace and project
* Deployment ID
* Request ID
* Invocation ID when relevant
* Approximate timestamp and timezone
* Environment and domain
* Expected versus observed behavior
* Screenshot or CLI output of `easel logs --request-id … --expand`
Related guides [#related-guides]
* [Request details](/docs/observability/request-details)
* [Logs](/docs/observability/logs)
* [Tracing](/docs/observability/tracing)
* [Retention and limits](/docs/observability/limits)
# Core concepts
Project [#project]
A project connects source code and platform configuration to a deployable application. It contains build settings, environment variables, domains, security controls, and deployment history.
Deployment [#deployment]
A deployment is an immutable version of an application built from a specific source revision and configuration. Every successful deployment receives a unique URL.
Environment [#environment]
An environment selects the settings used to build and run a deployment. Easel currently distinguishes Preview and Production configuration.
An environment is not a long-running server and is not the same thing as a deployment.
Preview deployment [#preview-deployment]
A Preview deployment is built with Preview configuration. Branch and pull-request URLs can move forward to the latest ready deployment associated with that source context.
Production deployment [#production-deployment]
A Production deployment is built with Production configuration. It may be assigned to production domains automatically or remain staged until promoted.
Current deployment [#current-deployment]
The Current deployment is the Production deployment receiving traffic for production domains. Promoting or rolling back changes this assignment without modifying the deployment itself.
Deployment URL [#deployment-url]
A deployment URL identifies one immutable deployment. Branch, pull-request, and production URLs are aliases that may point to different deployments over time.
Static asset [#static-asset]
A static asset is a file produced by the build and served without application compute, such as HTML, JavaScript, CSS, fonts, and images.
Function [#function]
A Function runs server-side application code, including server-rendered routes, API handlers, loaders, actions, webhooks, and supported framework background work.
Request and invocation [#request-and-invocation]
A request is one HTTP exchange received by Easel. An invocation is an active Function execution session. One invocation may serve more than one request.
CDN cache [#cdn-cache]
The CDN cache stores complete HTTP responses and is evaluated before a Function is invoked.
Runtime Cache [#runtime-cache]
Runtime Cache stores application values accessed from Function code. It is separate from HTTP response caching.
Redirect and rewrite [#redirect-and-rewrite]
A redirect returns a 3xx response that tells the client to request another URL. A rewrite changes the internal destination while preserving the browser-visible URL.
Region and edge location [#region-and-edge-location]
An edge location receives and delivers requests. A compute region runs dynamic application code. These locations are not necessarily the same.
Request ID [#request-id]
A request ID uniquely identifies an Easel request and can be used to correlate response headers, request details, logs, traces, cache diagnostics, and security events.
# Platform limits
Easel applies limits to builds, deployments, delivery, Functions, security controls, observability, and workspace resources.
The canonical limits reference is [Reference: Limits](/docs/reference/limits). Use that page for exact current values.
Why limits exist [#why-limits-exist]
Limits protect platform reliability, bound resource consumption, and make application behavior predictable. Some limits are fixed platform constraints; others vary by plan or can be raised by agreement.
Before production launch [#before-production-launch]
Review limits when your application has:
* Large request or response bodies
* Long-running dynamic requests
* Streaming responses
* Large dependency bundles or deployment artifacts
* High concurrency or burst traffic
* Extensive custom firewall rules
* High-volume logs or traces
* Large cache entries or frequent invalidation
Do not infer a limit from a framework default or another hosting provider. Easel's enforced runtime and delivery limits are the source of truth.
# Platform architecture
Easel separates application builds from request delivery. A deployment is assembled once, published as immutable output, and then served through shared delivery and runtime systems.
Build plane [#build-plane]
The build plane turns source code into deployable artifacts.
```text
Git commit or CLI upload
↓
Install dependencies
↓
Run framework build
↓
Analyze build output
├─ static assets
├─ server functions
├─ routing metadata
├─ cache metadata
└─ image configuration
↓
Publish immutable deployment
```
The exact output depends on the framework. A Vite application may contain only static assets. A Next.js application may also contain server handlers, middleware, cached route output, and image optimization configuration.
Delivery plane [#delivery-plane]
The delivery plane receives every request to an Easel URL or connected domain.
```text
Request
↓
Platform protections
↓
Deployment protection
↓
Project firewall rules
↓
Routing, redirects, and rewrites
↓
CDN cache or static asset
↓ when application execution is required
Function routing
↓
Function instance
```
The delivery plane can complete requests without application compute. This reduces latency and avoids unnecessary Function usage.
Compute plane [#compute-plane]
Dynamic routes run in Easel Functions. A Function instance can process overlapping requests when the runtime and application permit it.
Applications must not depend on instance affinity, durable local files, or mutable process-wide state. Use external data stores or Runtime Cache for shared state.
Data and cache layers [#data-and-cache-layers]
Easel exposes two distinct cache systems:
| System | Stores | Accessed from | Typical use |
| ------------- | ----------------------- | ---------------- | --------------------------------- |
| CDN cache | Complete HTTP responses | Delivery network | Pages, assets, API responses |
| Runtime Cache | Application values | Function code | Database results, computed values |
A single request can use both. A Function can read data from Runtime Cache and return a response that is then stored in the CDN cache.
Control plane [#control-plane]
The dashboard, Git integration, CLI, and future public API operate the control plane. They create projects, configure environments, start deployments, assign domains, and expose operational data.
Control-plane actions do not change an immutable deployment. Changes to source code, build-time variables, or build settings require a new deployment. Traffic assignment can move between existing compatible Production deployments without rebuilding.
Observability plane [#observability-plane]
Easel records telemetry across request delivery and Function execution. Request IDs correlate client-visible responses with request details, logs, traces, cache decisions, security events, and Function invocations.
Because one Function invocation may process multiple requests, request and invocation records are related but not interchangeable.
Availability boundaries [#availability-boundaries]
A globally reachable delivery network does not imply that every service executes in every edge location. Static and cached responses may be served close to users while dynamic Functions run in documented compute regions.
See [Regions](/docs/reference/regions) and [Limits](/docs/reference/limits) for the current platform boundaries.
# Pricing and usage
Easel usage is driven by the work required to build, deliver, and execute an application. Included allowances, on-demand ranges, and regional rates live in [Pricing](/docs/pricing) and on the [pricing page](/pricing).
This guide explains the usage model. It does not duplicate price numbers that can change.
Main usage categories [#main-usage-categories]
Builds [#builds]
Build usage includes dependency installation, framework compilation, output analysis, and publication. Rebuilding the same source can still consume build resources when configuration or dependencies differ.
Bandwidth and delivery [#bandwidth-and-delivery]
Delivery usage includes bytes returned through Easel's network. Static assets, cached responses, and Function responses can all contribute to transfer.
Function execution [#function-execution]
Function usage is based on Function Requests and Function Duration. Function Requests are logical requests into your functions, not cloud-provider invoke counts. Post-response work continues to consume Function Duration until it completes or reaches the applicable limit.
In-function concurrency can allow one active instance to serve overlapping requests. Do not assume that request count maps one-to-one to instance count or invocation count.
Image optimization [#image-optimization]
Image Optimization is metered as Image Transformations on cache MISS and STALE only. See [Image Optimization pricing](/docs/pricing/image-optimization).
Observability [#observability]
Logs, metrics, traces, retention, and export can have plan-specific allowances or limits.
Security [#security]
Some security capabilities or higher limits may depend on the workspace plan.
What reduces usage [#what-reduces-usage]
* Serve immutable assets with long-lived cache headers.
* Cache eligible dynamic responses at the CDN.
* Use Runtime Cache for repeated application data or computation.
* Avoid unnecessary rebuilds in monorepos.
* Keep Function work bounded and move durable jobs to a queue or background system.
* Control verbose application logging in production.
Preview and Production usage [#preview-and-production-usage]
Preview deployments use platform resources in the same way as Production deployments. A high-volume Preview or automated branch workflow can therefore contribute meaningful build, bandwidth, Function, and observability usage.
Usage attribution [#usage-attribution]
Inspect usage in the dashboard by workspace and project. Breakouts by
deployment, environment, and resource category appear where the product exposes
them.
Avoiding unexpected usage [#avoiding-unexpected-usage]
1. Review build triggers and monorepo path filters.
2. Configure cache policies intentionally.
3. Inspect Function duration and request volume.
4. Set retention and export policies appropriate for the application.
5. Review plan limits before a launch or migration.
See [Limits](/docs/reference/limits) for technical ceilings and the [pricing page](/pricing) for current commercial terms.
# What is Easel?
Easel is a cloud platform for building, deploying, delivering, and operating modern web applications.
Connect a Git repository or deploy from the CLI. Easel builds the application, publishes static assets to its delivery network, runs server-side code in Functions, protects incoming traffic, and records request-level telemetry.
What you can deploy [#what-you-can-deploy]
Easel supports static sites, client-rendered applications, and full-stack JavaScript frameworks. Supported framework integrations include Next.js, TanStack Start, Nuxt, React Router, SvelteKit, and Vite.
A framework build can produce several kinds of output:
* Static HTML, JavaScript, CSS, fonts, and images
* Server-rendered routes and API handlers
* Middleware and routing metadata
* Cacheable pages and application data
* Image optimization requests
Easel maps each output to the appropriate platform service.
The platform in one request [#the-platform-in-one-request]
A request to an Easel deployment passes through the delivery network before it reaches application code.
```text
Visitor
↓
Easel delivery network
├─ security controls
├─ redirects and rewrites
├─ CDN cache
└─ static asset lookup
↓ when dynamic execution is required
Easel Function
↓
Database, API, or Runtime Cache
```
A request may complete at the edge without invoking a Function when it is blocked, redirected, served from cache, or matched to a static asset.
Deployment workflow [#deployment-workflow]
Every successful build creates an immutable deployment with its own URL. Git branches and pull requests can receive stable Preview URLs, while production domains point to the deployment currently assigned to Production.
This separation lets teams validate a build before release and roll production traffic back without rebuilding.
What Easel manages [#what-easel-manages]
Easel manages:
* Build execution and framework detection
* Deployment artifacts and immutable deployment URLs
* Static asset delivery and HTTP caching
* Dynamic Functions and runtime resources
* Domain routing and managed TLS
* Firewall controls and deployment protection
* Logs, metrics, traces, and request diagnostics
Your application remains responsible for its own business logic, authentication and authorization, data model, external services, and secure handling of credentials.
Where to go next [#where-to-go-next]
* Follow [Getting started](/docs/getting-started) to deploy an application.
* Read [Platform architecture](/docs/overview/platform-architecture) to understand the request and deployment model.
* Review [Frameworks](/docs/framework-guides) for integration-specific behavior.
* See [Core concepts](/docs/overview/core-concepts) for the terminology used throughout the documentation.
# Configuration reference
Use this page as an index of configuration surfaces. Detailed field behavior lives
on the linked product pages.
Project and build [#project-and-build]
* [Build configuration](/docs/deployments/build-configuration)
* [Monorepos](/docs/deployments/monorepos)
* [Git deployments](/docs/deployments/git)
* [Creating deployments](/docs/deployments/create)
Environments and variables [#environments-and-variables]
* [Environments](/docs/deployments/environments)
* [Environment variables](/docs/runtime/environment-variables)
* [Secrets](/docs/security/secrets)
Functions and runtime [#functions-and-runtime]
* [Function configuration](/docs/functions/configuration)
* [Function runtime](/docs/functions/runtime)
* [Function regions](/docs/functions/regions)
* [Background work](/docs/runtime/background-work)
* [Runtime Cache](/docs/runtime-cache)
Delivery [#delivery]
* [Routing](/docs/delivery/routing)
* [Redirects and rewrites](/docs/delivery/redirects-and-rewrites)
* [Caching](/docs/cdn/caching)
* [Headers](/docs/cdn/headers)
* [Compression](/docs/cdn/compression)
Domains and TLS [#domains-and-tls]
* [Domains](/docs/domains)
* [Domains and TLS](/docs/delivery/domains-and-tls)
* [Domains reference](/docs/domains/reference)
Security [#security]
* [WAF rules](/docs/security/waf-rules)
* [Access protection](/docs/security/deployment-protection)
* [Security evaluation order](/docs/security/request-chain)
CLI [#cli]
* [CLI overview](/docs/cli)
* [Deploy from the CLI](/docs/cli/deploy)
# Error codes
Easel failures surface through dashboard status, CLI output, HTTP responses, and
logs. Prefer the request ID, deployment ID, and product-specific troubleshooting
guides over inventing undocumented error symbols.
What to capture [#what-to-capture]
When a build, deployment, or request fails, record:
| Field | Why it matters |
| ------------- | -------------------------------------------- |
| Surface | Dashboard, CLI, build, request, or webhook |
| Message | Human-readable failure text |
| Request ID | Correlates delivery and Function telemetry |
| Deployment ID | Identifies the immutable artifact |
| Timestamp | Narrows log and metric windows |
| Retryable | Whether retrying without changes may succeed |
Categories and where to look [#categories-and-where-to-look]
Build errors [#build-errors]
Dependency installation, framework detection, command failure, output
validation, and timeouts. See
[Deployment troubleshooting](/docs/deployments/troubleshooting) and
[Build configuration](/docs/deployments/build-configuration).
Deployment errors [#deployment-errors]
Publication, artifact upload, domain assignment, cancellation, and invalid
state transitions. See [Managing deployments](/docs/deployments/manage) and
[Promoting deployments](/docs/deployments/promote).
Request and routing errors [#request-and-routing-errors]
Invalid host, redirect loops, route not found, malformed headers, and body
limits. See [Routing](/docs/delivery/routing),
[CDN troubleshooting](/docs/cdn/troubleshooting), and
[Debugging](/docs/guides/debugging).
Function errors [#function-errors]
Initialization, runtime crash, timeout, out-of-memory, and invalid responses.
See [Function observability](/docs/observability/functions) and
[Function limits](/docs/functions/limits).
Domain and TLS errors [#domain-and-tls-errors]
Invalid DNS, ownership conflicts, certificate issuance, and renewal. See
[Domain troubleshooting](/docs/domains/troubleshooting) and
[HTTPS and TLS](/docs/cdn/https-and-tls).
Security errors [#security-errors]
Blocked, challenged, or protected-deployment responses. See
[Security troubleshooting](/docs/security/troubleshooting) and
[Firewall observability](/docs/security/firewall-observability).
API and CLI errors [#api-and-cli-errors]
Authentication, authorization, validation, and service availability. See
[CLI authentication](/docs/cli/authentication) and [API status](/docs/api).
Request IDs are not error codes [#request-ids-are-not-error-codes]
A request ID identifies one request and helps correlate telemetry. It does not
describe the failure category. Include both the message and the request ID when
contacting support.
# Limits reference
This page is the entry point for enforced Easel limits. Product pages keep the
detailed tables; use the links below for exact current values.
Builds and deployments [#builds-and-deployments]
See [Build configuration](/docs/deployments/build-configuration) and
[Deployment troubleshooting](/docs/deployments/troubleshooting) for build and
artifact constraints that appear during deploy.
Delivery [#delivery]
See [CDN](/docs/cdn), [Caching](/docs/cdn/caching), and
[Headers](/docs/cdn/headers) for request, response, cache, and header limits
that apply at the delivery layer.
Functions [#functions]
See [Function limits](/docs/functions/limits) for duration, memory, CPU, request
body size, deployment bundle size, environment variable size, and related
execution ceilings.
Runtime Cache [#runtime-cache]
See [Runtime Cache](/docs/runtime-cache) for key, value, TTL, and invalidation
constraints.
Domains and TLS [#domains-and-tls]
See [Domains reference](/docs/domains/reference) and
[HTTPS and TLS](/docs/cdn/https-and-tls) for hostname, DNS, and certificate
constraints.
Security [#security]
See [Security limits](/docs/security/limits) for firewall rule counts,
conditions, IP rules, and related ceilings.
Observability [#observability]
See [Observability retention](/docs/observability/limits) for dashboard time
windows, log capture bounds, and query limits.
Raising a limit [#raising-a-limit]
Some limits are fixed platform constraints. Others may be plan-dependent or
adjustable by agreement. Contact [hello@easel.sh](mailto:hello@easel.sh) when a
production workload needs a higher ceiling, and include the limit name and
observed failure mode.
# Regions
Easel distinguishes edge delivery locations from Function compute regions.
Edge delivery [#edge-delivery]
Requests enter Easel through its delivery network. Static assets and cacheable
responses may be served from an edge location without invoking application
compute.
Do not interpret the number of edge locations as the number of places where
Functions run.
Function compute [#function-compute]
Dynamic routes run in Function compute regions supported by the platform.
| Region ID | Location | Available for Functions | Selection |
| --------- | -------------------------------- | ----------------------- | ---------------------------------------------------- |
| `iad` | US East (Northern Virginia, USA) | Yes | Platform default; currently the only Function region |
Additional Function regions are not available yet. Region placement is fixed by
the platform today. Do not rely on route-level or project-level region
configuration examples until the product exposes them.
The delivery layer may attach the Function region on the request your
application receives:
```http
X-Easel-Function-Region: iad
```
See [Function regions](/docs/functions/regions) and
[Request and response headers](/docs/cdn/headers).
Data locality [#data-locality]
Place latency-sensitive databases and APIs near the Function compute region.
Edge delivery cannot remove the network trip between a Function and a distant
data service.
Observability [#observability]
Request and invocation records can expose edge and compute context separately
where available. See [Function observability](/docs/observability/functions).
# Build pricing
**Build Execution** is vCPU-minutes while the builder sandbox is ready, until it is deleted, multiplied by the configured vCPU count. Queue time is not billed. Baker and probe sandboxes are not billed.
Hobby and Pro include **100 Standard build minutes** per month. Standard is the 2 vCPU build machine. Enhanced (4 vCPU) consumes the grant twice as fast. After the grant, Hobby builds stop until you upgrade to Pro. Pro continues from usage credits, then on-demand rates.
Included allowances and on-demand ranges are in [What each meter counts](/docs/pricing/usage).
Easel checks remaining build allowance before starting a build. Exhausted Hobby allowance requires an upgrade. Exhausted Pro credit without a top-up can block new builds.
See [Build configuration](/docs/deployments/build-configuration).
# Cache pricing
ISR and Runtime Cache share **Cache Read Units** and **Cache Write Units**. A unit is 8 KB: `ceil(bytes / 8192)`. A 0-byte miss is 0 units.
Regional multipliers apply after the 8 KB conversion. Remaining cache units in the dashboard are base-region-equivalent.
Included allowances and on-demand ranges are in [What each meter counts](/docs/pricing/usage).
Image Optimization cache hits are not cache-write units and are not Image Transformations. See [Image Optimization pricing](/docs/pricing/image-optimization) and [Runtime Cache](/docs/runtime-cache).
# Usage credit and top-up
Pro includes $20 of usage credit each month (2,000 credits, where 1 credit is $0.01). Direct included allowances on a meter are consumed first. Further usage draws this credit at the meter’s base (iad) on-demand rate, because tracked quantities are already region-normalized.
Hobby has no usage credit. Work beyond Hobby included limits requires Pro.
Top-up [#top-up]
You can purchase a **$10** top-up for **1,000 credits**. Purchased credits persist independently of the monthly Pro grant.
On the billing page you can enable **auto top-up** for usage credit. You must set a monthly purchase limit. A failed charge does not invent balance.
Unused monthly credit does not roll over. See [How Easel pricing works](/docs/pricing) and the [pricing page](/pricing).
# Data transfer pricing
Delivery has two transfer meters.
**Edge Data Transfer** counts bytes from the edge to the client. Cached, static, and function responses all contribute when bytes leave the edge.
**Origin Transfer** counts bytes on the origin-to-edge fetch (`originBytesIn` only). It does not add request `originBytesOut`. The region is the function’s AWS region when the origin is a function, otherwise the edge region.
Included allowances and on-demand ranges are in [What each meter counts](/docs/pricing/usage).
Both meters use regional multipliers. See [regional rates](/docs/pricing/regions).
# Function pricing
Functions have two meters: **Function Requests** and **Function Duration**.
Function Requests count logical application requests into your functions (pages, route handlers, server actions, and similar). They are not AWS Lambda invocation counts. Overlapping in-function concurrency can serve more than one request on one billed execution.
Function Duration is GB-hours from billed duration and configured memory on the function report, recorded once per underlying execution id. Wall-clock time on each HTTP response is not a separate duration charge.
Hobby includes **100 GB-hours** of Function Duration and **100,000** Function Requests per month. Pro includes **1,000 GB-hours** and **1,000,000** Function Requests. On-demand Function Duration is **$0.18 / GB-hour** (flat across regions at launch). Full included tables and on-demand ranges are in [What each meter counts](/docs/pricing/usage).
What is not billed here [#what-is-not-billed-here]
* Queue time before a build or a cold start is not Function Duration.
* Static and cached responses that never reach a function do not create Function Requests.
See [Functions](/docs/functions) for runtime behavior and [regional rates](/docs/pricing/regions) for duration multipliers.
# Image Optimization pricing
Image Optimization is billed per **Image Transformation**, in thousands, in the **edge delivery region**.
A transformation is billed on cache **MISS** and **STALE** only. A cache **HIT** is not an Image Transformation. Easel does not bill separate Image Cache Read or Image Cache Write meters.
Hobby includes 5,000 transformations per month. Pro has no included grant: transformations draw from usage credit at the on-demand rate.
Base rate is $0.05 per 1,000 transformations in `iad`. Other regions use the multipliers below (regional USD ÷ 0.05). Published marketing range: $0.05–$0.0812 per 1,000.
See [Image Optimization](/docs/runtime/image-optimization) for how transforms are requested.
# How Easel pricing works
Hobby is free within published included allowances. Pro is $20 per month and includes $20 of metered usage credit. On-demand rates apply after included allowances and Pro credit are consumed.
Numbers on this page come from the same catalog as the [pricing page](/pricing). Remaining usage is measured in **base-region-equivalent** units: regional multipliers are applied before usage is counted against an allowance.
Plans [#plans]
* **Hobby**: included allowances only. No usage credit pool. Stays free inside those limits.
* **Pro**: $20 platform fee, $20 included usage credit each month, higher included allowances on several meters.
* **Enterprise**: custom contracts for SSO, multi-region failover, and platform SLAs. Contact us.
Unused included usage and unused Pro credit do not roll over.
What you are billed for [#what-you-are-billed-for]
Easel meters Edge Requests, Edge Data Transfer, Origin Transfer, Function Requests, Function Duration, cache units, Image Transformations, Build Execution, Rate Limiting, and WAF inspection. Function Requests are application-level requests into your functions, not cloud-provider invoke counts.
Observability export meters are declared for a later release and are not billed today.
Next steps [#next-steps]
* [What each meter counts](/docs/pricing/usage)
* [Regional rates](/docs/pricing/regions)
* [Usage credit and top-up](/docs/pricing/credits)
# Regional rates
On-demand prices differ by region. Easel converts usage into **base-region-equivalent** units with a regional multiplier, then counts that quantity against your allowance and credit.
A 1 GB transfer in São Paulo (`gru`) with a 1.7× egress multiplier counts as 1.7 GB against Edge Data Transfer remaining. The billing UI remaining figure is that normalized quantity, not “GB remaining in every region.”
Unknown regions are not billed and are not mapped to `iad`.
Published retail by region [#published-retail-by-region]
Rates below are USD at the meter’s billing increment (per GB, per 1M, per 1K, or per GB-hour).
Function Requests and Build Execution are not region-multiplied. Image transformation multipliers follow the Image Optimization regional table on [Image Optimization pricing](/docs/pricing/image-optimization).
# Security pricing
Security meters apply only when a request enters the matching path.
**Rate Limiting** counts requests that were subject to a rate-limit rule and allowed. Requests that never entered a rate-limit path are not counted. Requests that were limited (HTTP 429) are not counted as allowed.
**WAF Inspected Requests** counts requests on the WAF inspect path. **WAF Inspected Payload** counts the inspected request-body prefix only, not response bodies.
Hobby and Pro have no included WAF grant at launch. Rate Limiting has an included monthly allowance.
Included allowances and on-demand ranges are in [What each meter counts](/docs/pricing/usage).
See [Firewall](/docs/security/firewall) and [WAF rules](/docs/security/waf-rules).
# What each meter counts
Each meter counts one kind of work. Dashboard remaining values are **base-region-equivalent**: a request or gigabyte in a higher-priced region consumes more of the same allowance than the same work in `iad`.
Edge and delivery [#edge-and-delivery]
* **Edge Requests**: one count per completed response at the edge.
* **Edge Data Transfer**: bytes sent from the edge to the client, billed per GB.
* **Origin Transfer**: bytes fetched from origin into the edge (`originBytesIn` only). Response bytes from origin to the visitor are Edge Data Transfer, not Origin Transfer.
Functions [#functions]
* **Function Requests**: one count per logical function request. This is not an AWS Lambda invoke count. Concurrent or fluid execution can serve overlapping work without a 1:1 map to cloud invokes.
* **Function Duration**: GB-hours from the billed duration and configured memory on the function report, once per underlying execution id.
See [Function pricing](/docs/pricing/functions).
Cache and images [#cache-and-images]
* **Cache Read Units** and **Cache Write Units**: ISR and Runtime Cache share these meters. Units are `ceil(bytes / 8192)`. Zero-byte misses are 0 units.
* **Image Transformations**: one transformation on cache **MISS** or **STALE**. Cache **HIT** is not billed. See [Image Optimization pricing](/docs/pricing/image-optimization).
Builds and security [#builds-and-security]
* **Build Execution**: builder sandbox ready-to-delete time × configured vCPUs. Queue time and probe/baker sandboxes are excluded. Hobby and Pro include 100 Standard (2 vCPU) build minutes per month. Hobby stops at that grant. Pro continues from usage credits.
* **Rate Limiting**: requests that entered a rate-limit path and were allowed. Requests that never hit a rate-limit rule are not counted. Blocked (429) requests are not counted as allowed.
* **WAF Inspected Requests** and **WAF Inspected Payload**: requests and inspected request-body prefix on the WAF inspect path. Response bodies are not inspected for this meter.
# Background work
Some application work does not need to block the HTTP response. Easel supports framework APIs that register post-response work within the active Function lifecycle.
Post-response work is not a durable job queue.
Post-response work [#post-response-work]
A supported framework API can return the response and continue work before the invocation ends.
For example, Next.js provides `after()`:
```ts
import { after } from "next/server";
export async function POST(request: Request) {
const event = await request.json();
after(async () => {
await recordAnalyticsEvent(event);
});
return Response.json({ accepted: true });
}
```
The client can receive the response before the callback completes, but the Function remains active and continues consuming duration.
Appropriate uses [#appropriate-uses]
Post-response work is appropriate for short, best-effort tasks such as:
* Recording non-critical analytics
* Updating a secondary cache
* Sending a lightweight notification
* Completing a bounded cleanup step
Use a durable job system when work [#use-a-durable-job-system-when-work]
* Must survive Function termination
* Requires automatic retries
* May exceed the Function duration limit
* Must run independently of the originating request
* Requires scheduling, fan-out, or concurrency control
* Must guarantee eventual completion
A durable pattern is:
```text
HTTP request
↓
Validate and persist job
↓
Return 202 Accepted
↓
Worker processes job with retries
```
Failure behavior [#failure-behavior]
A successful HTTP response does not prove that post-response work completed. Log failures and make non-idempotent operations safe to retry when possible.
Limits [#limits]
Post-response work shares the Function's duration, memory, CPU, networking, and shutdown boundaries. See [Function limits](/docs/functions/limits).
# Environment variables
Environment variables provide configuration to builds and Functions without committing values to source control.
Environment scopes [#environment-scopes]
Easel separates Preview and Production values. A deployment receives values from the environment used to build it.
| Scope | Used by |
| ---------- | --------------------------------------------------- |
| Preview | Branch, pull-request, and other Preview deployments |
| Production | Production deployments |
Changing a variable does not mutate an existing immutable deployment. Create a new deployment for the change to take effect.
Build-time variables [#build-time-variables]
Build tools and frameworks can read variables while compiling the application.
```js
const apiOrigin = process.env.API_ORIGIN;
```
Public prefixes such as `NEXT_PUBLIC_`, `VITE_`, and framework equivalents can embed values into browser JavaScript. Never place secrets in public variables.
Runtime variables [#runtime-variables]
Server-side routes and Functions can read environment variables at runtime through the framework's normal API.
```js
const databaseUrl = process.env.DATABASE_URL;
```
Treat all secret values as sensitive even when they are only available server-side.
Variable names and values [#variable-names-and-values]
Use descriptive uppercase names. Avoid storing large files or structured
credentials when a dedicated secret mechanism is required.
Combined environment variable names and values are subject to the Function
environment size limit. See [Function limits](/docs/functions/limits).
Local development [#local-development]
Keep local values in the framework's supported local environment files and exclude secret-bearing files from Git. Easel does not automatically synchronize local files with project settings unless a documented CLI command provides that behavior.
Rotation [#rotation]
To rotate a credential:
1. Create the replacement credential at the provider.
2. Update Preview and validate a new Preview deployment.
3. Update Production and create a Production deployment.
4. Promote the new deployment.
5. Revoke the previous credential after rollback risk has passed.
Troubleshooting [#troubleshooting]
When a value is missing or stale, verify:
* The correct Easel project
* Preview versus Production scope
* Exact variable name and capitalization
* Whether the variable is required during build or runtime
* Whether a new deployment was created after the change
* Whether the framework embeds public variables at build time
# Image optimization
Easel image optimization transforms source images into appropriately sized and encoded responses for supported framework integrations.
How it works [#how-it-works]
A framework image component generates an optimization request containing the source image and requested dimensions. Easel validates the request, retrieves or reads the source, performs the supported transformation, and caches the result.
```text
Browser image request
↓
Validate source and dimensions
↓
Optimization cache lookup
↓ miss
Fetch or read source image
↓
Resize and encode
↓
Cache and return response
```
Framework support [#framework-support]
Use the framework-native image component when the matching Easel framework guide marks image optimization as supported.
Static applications can serve pre-generated responsive images directly from deployment assets.
Remote images [#remote-images]
Remote image sources must match the framework and platform allowlist configuration. Restrict patterns to trusted hosts and paths. Broad remote-image patterns can allow unintended fetches and increase resource usage.
Cache behavior [#cache-behavior]
Transformed variants are cached independently based on source, dimensions, format, and other supported transformation parameters. Updating a remote image at the same URL may not immediately invalidate previously cached variants.
Performance guidance [#performance-guidance]
* Provide explicit width and height to reduce layout shift.
* Use responsive `sizes` values so browsers do not request unnecessarily large images.
* Prefer modern source formats where practical.
* Avoid generating excessive near-duplicate dimensions.
* Keep remote origins reliable and cacheable.
Security [#security]
Image optimization fetches source images server-side. Restrict remote patterns
to trusted hosts and paths. Prefer framework-native configuration documented in
the matching [framework guide](/docs/framework-guides).
Troubleshooting [#troubleshooting]
Check the framework guide, remote-source allowlist, requested dimensions, source
response headers, and related limits when an image returns an error or bypasses
optimization.
# Attack Mode
Attack Mode protects a project during active abuse by requiring browser clients
to complete a verification step before accessing application content.
In the dashboard this control appears as **Attack challenge mode**.
Use Attack Mode as a temporary defensive control during:
* Sudden request floods
* Automated scraping
* Credential-stuffing attempts
* Broad malicious scanning
* Attacks that are difficult to isolate with a narrow rule
Attack Mode is not a replacement for application authentication, authorization,
or rate limiting.
How Attack Mode works [#how-attack-mode-works]
When Attack Mode applies to a request:
1. Easel evaluates whether the request is eligible for browser verification.
2. Unverified clients receive a challenge page with HTTP status **429**.
3. The browser completes a proof-of-work verification.
4. The browser posts the result to `/.well-known/easel-challenge/verify`.
5. On success, Easel sets a short-lived session cookie (`easel_ch_pass`, about
one hour, bound to hostname and deployment).
6. The client continues to the application without repeating the challenge until
the session expires.
Challenge responses use `Cache-Control: no-store` so intermediaries do not cache
the interstitial.
Enable Attack Mode [#enable-attack-mode]
1. Open the project.
2. Open **Project settings**.
3. Find **Attack challenge mode**.
4. Review the impact on APIs, bots, and non-browser clients.
5. Optionally enable **Allow verified bots**.
6. Turn Attack Mode on and save.
7. Monitor firewall events and application health.
Scope [#scope]
Attack Mode is project-wide. When enabled, it applies to hostnames that serve
the project, including production and preview URLs, unless a request is exempt.
Exemptions include:
* A valid Attack Mode session cookie
* A matching **Bypass attack challenge** custom rule
* Verified bots when **Allow verified bots** is enabled
* Trusted internal edge fetches
* BotID opaque verification paths used by the BotID SDK
Custom **Challenge** rules still apply before Attack Mode. See
[Security evaluation order](/docs/security/request-chain).
Browser verification [#browser-verification]
Verification requires a browser that can run the challenge page and store the
session cookie. It does not prove that a visitor is human; it only shows that
the client completed the configured verification flow.
Verification is bound to the hostname and deployment identity. Changing host,
deployment, or clearing cookies can require a new solve.
APIs and non-browser clients [#apis-and-non-browser-clients]
Attack Mode can disrupt:
* API clients
* Webhooks
* Mobile applications
* Command-line clients
* Monitoring systems
* Automated integrations
Before enabling it, create narrow **Bypass attack challenge** rules for trusted
machine traffic when needed. Recommended signals include:
* Trusted IP ranges
* Dedicated webhook paths
* Known client headers that your edge can trust
Continue validating application-level signatures in your code. Firewall rules
cannot replace webhook signature checks.
Bots [#bots]
Verified bots may bypass Attack Mode when **Allow verified bots** is enabled.
See [Bot traffic](/docs/security/bots). A bot should not be trusted solely
because its user agent resembles a known crawler.
Disable Attack Mode [#disable-attack-mode]
Disable Attack Mode after the attack subsides and narrower protections are in
place.
Before disabling it:
1. Review matched traffic.
2. Identify stable malicious patterns.
3. Convert appropriate patterns into custom rules.
4. Confirm application capacity is healthy.
5. Continue monitoring after deactivation.
Related guides [#related-guides]
* [Custom rules](/docs/security/custom-rules)
* [Bot traffic](/docs/security/bots)
* [Firewall observability](/docs/security/firewall-observability)
* [Security troubleshooting](/docs/security/troubleshooting)
# Bot traffic
Automated traffic includes legitimate crawlers, monitoring systems,
integrations, scrapers, scanners, and abusive bots.
A user-agent string alone cannot reliably prove a bot’s identity.
Verified bots [#verified-bots]
A verified bot is an automated client whose identity has been validated using
stronger evidence than a user-agent claim.
Easel may verify bots using:
* Published IP ranges
* Forward and reverse DNS
* Cryptographic request signatures (Web Bot Auth)
Examples include major search crawlers and selected service bots. The verified
set can change as providers update their infrastructure.
Attack Mode bypass [#attack-mode-bypass]
When Attack Mode is on and **Allow verified bots** is enabled, verified bots may
skip the browser challenge so search indexing and approved integrations can
continue.
Verified-bot bypass applies to Attack Mode only. It does not:
* Skip custom **Deny**, **Redirect**, or **Challenge** rules
* Skip [deployment protection](/docs/security/deployment-protection)
* Skip [platform protections](/docs/security/platform-protections)
You can still block a verified bot with an explicit custom rule. Arbitrary
clients cannot claim verified status by forging a user agent.
Customer controls [#customer-controls]
Use custom firewall rules to:
* Block a specific path for unwanted crawlers
* Challenge unverified automation
* Bypass Attack Mode for monitoring IPs
* Deny known abusive sources
Prefer IP, ASN, path, and verified-bot behavior over fragile user-agent matching
when stronger signals are available.
AI crawlers [#ai-crawlers]
Some AI crawlers appear in the verified-bot registry when their identity can be
validated. Others are unverified.
Blocking by user agent alone is easy to evade. Combine path restrictions,
authentication, and Attack Mode or custom challenges when you need stronger
controls.
Application visibility [#application-visibility]
Bot classification is used during edge security evaluation and may appear in
security observability. Do not rely on a client-supplied bot identity header as
proof of verification.
For application-level bot detection in frameworks that support it, use BotID in
your application code. BotID opaque verification paths are excluded from the
Attack Mode interstitial so the SDK can complete its flow.
Related guides [#related-guides]
* [Attack Mode](/docs/security/attack-mode)
* [Custom rules](/docs/security/custom-rules)
* [Firewall observability](/docs/security/firewall-observability)
# Custom firewall rules
Custom rules let you define project-specific security policies without modifying
application code.
Rules are project-scoped: they apply to every hostname that serves that project,
including preview URLs, production URLs, and custom domains.
Create a rule [#create-a-rule]
1. Open the project.
2. Open **Project settings**.
3. Scroll to **Custom WAF rules**.
4. Choose **Add rule**.
5. Enter a descriptive name.
6. Add one or more conditions.
7. Select an action.
8. Review the rule order.
9. Toggle **Active** and save.
10. Confirm matches in firewall observability.
Clearing all rules and saving stores an empty ruleset.
How matching works [#how-matching-works]
* **Rule order matters.** Easel evaluates active rules from top to bottom. The
first matching rule applies; lower rules are not considered for that request.
* **Condition groups (OR).** A rule can have multiple groups. If any group
matches, the rule matches.
* **Conditions inside a group (AND).** Every condition in a group must be true
for that group to match.
* **Negate.** Inverts a single condition after the operator runs. Prefer
explicit operators such as **Does not equal** or **Is not any of** for new
rules.
Conditions [#conditions]
Each condition has a type, an operator, and either a single value or a values
list (one per line) for **Is any of** / **Is not any of**. Some types use a key
(header name, query parameter name, or cookie name).
Types [#types]
| Type | What is matched |
| ----------------------------- | -------------------------------------------------------------------------------- |
| **Request path (normalized)** | URL path with consistent trailing-slash handling. |
| **Raw path** | Path as received, without that normalization step. |
| **Route pattern** | The route pattern from your deployment that matched this request. |
| **Method** | HTTP method, compared in uppercase (`GET`, `POST`, …). |
| **User-Agent** | The `User-Agent` header. |
| **Request header** | A header by key. Legacy `Name:expected` in value is supported when key is empty. |
| **Query string (full)** | Everything after `?` in the URL. |
| **Query parameter** | A single query parameter; set key to the parameter name. |
| **Cookie** | A named cookie (key), or the raw `Cookie` header when key is empty. |
| **Hostname** | Host without port. |
| **Environment** | Deployment environment (`production` or `preview`). |
| **IP / CIDR** | Client IP after trusted proxy handling. See [IP rules](/docs/security/ip-rules). |
| **Edge region** | The edge region that handled the request. |
| **Geo continent / country** | Continent or country derived from the client IP. |
| **AS number** | Autonomous system number (ASN) derived from the client IP. |
| **Server action (Next.js)** | Matches `Next-Action` (falls back to `Next-Router-State-Tree` if empty). |
Operators [#operators]
| Label | Operand |
| ------------------------------------------------------ | --------------------- |
| **Equals** / **Does not equal** | Single value |
| **Is any of** / **Is not any of** | Values (one per line) |
| **Starts with** / **Does not start with** | Single value |
| **Ends with** / **Does not end with** | Single value |
| **Contains** / **Does not contain** | Single value |
| **Matches expression** / **Does not match expression** | Regular expression |
Validate regex rules with **Log** first. Patterns that work in JavaScript may
still fail to compile on the edge.
Geo and ASN [#geo-and-asn]
Geo country, geo continent, and ASN conditions use IP address data powered by
[IPLocate.io](https://www.iplocate.io) (CC BY-SA 4.0). Comparisons for country
and continent are case-normalized to uppercase.
Trusted client IP [#trusted-client-ip]
For IP, geo, and ASN conditions, the edge resolves the client IP from the
connection that reaches Easel. Easel honors `X-Forwarded-For` only on its
trusted edge path. Client-supplied forwarding headers from untrusted peers are
ignored.
Actions [#actions]
| Action | Effect |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Log** | Records a firewall observation and continues to your app. |
| **Deny (403)** | Responds with 403 Forbidden. The request does not reach your deployment. |
| **Challenge** | Serves a browser proof-of-work checkpoint (same family of flow as Attack Mode). After success, the edge sets a session cookie (about one hour). |
| **Bypass attack challenge** | Skips project-wide Attack Mode only. Other platform protections still apply. |
| **Redirect** | Responds with an HTTP redirect. Set a 3xx status and Location (absolute `https://…` URL recommended). |
**Challenge** rules use the same verification endpoint as Attack Mode. The edge
always allows `/.well-known/easel-challenge/*` so verification can complete
without looping.
Recommended rollout [#recommended-rollout]
1. Create a rule with **Log** and confirm traffic in observability.
2. Refine conditions until only the traffic you care about matches.
3. Change the action to **Deny**, **Challenge**, **Bypass**, or **Redirect**.
Observe first, then enforce.
Current limitations [#current-limitations]
* No per-rule rate limiting in the dashboard yet.
* No time-based IP ban from rule settings.
* Rules are ordered; there is no separate priority number beyond list order.
* TLS fingerprint matching is not available yet.
Examples [#examples]
Block a sensitive path by country [#block-a-sensitive-path-by-country]
```text
Path starts with /admin
Country is not US
Action: Deny
```
Bypass Attack Mode for a webhook path [#bypass-attack-mode-for-a-webhook-path]
```text
Path starts with /api/webhooks/
Action: Bypass attack challenge
```
Continue validating webhook signatures in application code.
Challenge suspicious login traffic [#challenge-suspicious-login-traffic]
```text
Path equals /login
Method equals POST
User agent contains HeadlessChrome
Action: Challenge
```
Observe an API client before enforcing [#observe-an-api-client-before-enforcing]
```text
Path starts with /api
Header x-client-version does not exist
Action: Log
```
Related guides [#related-guides]
* [Firewall](/docs/security/firewall)
* [Attack Mode](/docs/security/attack-mode)
* [IP rules](/docs/security/ip-rules)
* [Firewall observability](/docs/security/firewall-observability)
* [Security troubleshooting](/docs/security/troubleshooting)
# Deployment protection
Access protection controls who can open a deployment before application code
runs. Easel currently provides this through **Deployment Protection** policies.
Deployment protection controls who can access a deployment after the request
passes traffic-level security checks.
It is designed for:
* Preview deployments
* Branch deployments
* Pull request previews
* Unique deployment URLs
* Staged Production deployments that are not Current
Protection method [#protection-method]
Easel provides **workspace authentication** (SSO through the Easel app host).
When deployment protection is enabled, visitors must sign in with a workspace
account before they can view protected deployment URLs. After a successful
sign-in, the edge sets a session cookie (`easel_dp`, about one hour).
Where to configure [#where-to-configure]
1. Open the project.
2. Open **Project settings**.
3. Find **Deployment protection**.
4. Enable **Require workspace sign-in**.
5. Save.
Allow a short CDN cache delay after toggling.
Security layers [#security-layers]
Deployment protection is separate from the firewall.
A request may:
1. Pass platform protections.
2. Pass custom firewall rules and Attack Mode.
3. Still be denied because the requester is not authorized to view the
deployment.
Custom firewall actions do not bypass deployment authentication.
What is protected [#what-is-protected]
When enabled, visitors need workspace sign-in for:
* Preview hostnames on `preview.easelusercontent.com` (commit and branch URLs)
* Any deployment that is not the current production release
The following stay public:
* The canonical production subdomain for the current production deployment
* LIVE custom domains on the current production deployment
Preview deployments [#preview-deployments]
By default, preview hostnames are publicly reachable unless deployment
protection is enabled.
Preview responses also send `X-Robots-Tag: noindex, nofollow, noarchive` so
crawlers skip indexing. `noindex` is not an access control.
See [Preview deployments](/docs/deployments/previews).
Forks and untrusted code [#forks-and-untrusted-code]
Treat Preview configuration as untrusted-input space:
* Keep Production secrets out of Preview variables
* Enable deployment protection when previews must not be public
See [Secrets](/docs/security/secrets) and
[Deployment environments](/docs/deployments/environments).
Related guides [#related-guides]
* [Preview deployments](/docs/deployments/previews)
* [Security evaluation order](/docs/security/request-chain)
* [Workspace security](/docs/security/workspace-security)
# Firewall observability
Firewall observability connects security decisions to request activity.
Use it to:
* Debug a custom rule
* Investigate an attack
* Confirm Attack Mode behavior
* Identify false positives
* Determine whether application code ran
* Measure the impact of a policy change
Firewall events [#firewall-events]
Firewall and edge request views can include:
* Timestamp
* Request ID
* Project and deployment
* Domain
* Client IP, subject to permissions and privacy controls
* Method and path
* Action
* Rule ID
* Country and ASN, when available
* Response status
Actions [#actions]
Customer-facing action values you may see include:
```text
deny
challenge
challenge_pass
challenge_fail
redirect
log
bypass
```
Platform protections may also surface actions such as `ban` or `throttle` on
blocked or rate-limited traffic.
Use stable machine-readable values when filtering, even when dashboard labels
change.
Decision sources [#decision-sources]
When describing where a decision came from, prefer product concepts:
* Platform protection
* Custom rule
* Attack Mode
* Deployment protection
Do not rely on internal vendor names as part of the public event schema.
Response metadata [#response-metadata]
For custom-rule denials and some redirect failures, responses may include:
```text
X-Easel-Firewall-Action
X-Easel-Firewall-Rule-Id
```
Challenge responses may also include:
```text
X-Easel-Mitigated: challenge
X-Easel-Challenge-Token
```
Treat these as operational debugging signals. Incoming client copies of security
headers are not a trust boundary.
Rule testing [#rule-testing]
A safe workflow is:
1. Create a rule with the **Log** action.
2. Filter events by the rule ID or path.
3. Review expected and unexpected matches.
4. Refine the rule.
5. Change the action to **Deny**, **Challenge**, **Bypass**, or **Redirect**.
6. Continue monitoring after enforcement.
Challenge pass and fail counts reflect verification outcomes at
`/.well-known/easel-challenge/verify`, not every page view.
Privacy [#privacy]
Client IP and geographic information may be sensitive. Limit access to workspace
members who need it for operations, and avoid exporting raw client identifiers
into systems that do not require them.
Related guides [#related-guides]
* [Custom rules](/docs/security/custom-rules)
* [Attack Mode](/docs/security/attack-mode)
* [Security troubleshooting](/docs/security/troubleshooting)
* [Observability](/docs/observability)
* [Security events](/docs/observability/security)
# Firewall
The Easel Firewall evaluates incoming requests before they reach your
application.
Use it to block known abusive traffic, protect sensitive routes, challenge
suspicious browsers, or observe traffic patterns without changing application
code.
Firewall components [#firewall-components]
The project firewall includes:
* [Custom rules](/docs/security/custom-rules)
* [IP conditions](/docs/security/ip-rules) inside custom rules
* [Attack Mode](/docs/security/attack-mode)
* [Bot classification](/docs/security/bots) used by Attack Mode exemptions
Platform protections remain active independently of the project firewall.
Where to configure [#where-to-configure]
1. Open the project.
2. Open **Project settings**.
3. Configure **Custom WAF rules** and **Attack challenge mode**.
Rule changes save on the project. The edge picks them up after a short delay.
You do not need to redeploy to update rules.
Rule anatomy [#rule-anatomy]
A firewall rule has:
* A name
* One or more condition groups
* An action
* An enabled (active) state
* A position in the ordered list
Example:
```text
Name: Block admin access outside the office
Conditions:
Path starts with /admin
AND
IP is not any of the office addresses
Action:
Deny
```
Conditions [#conditions]
Supported request fields include:
| Field | Example |
| ------------------------ | ------------------------- |
| Hostname | `api.example.com` |
| Path (normalized or raw) | `/admin` |
| Method | `POST` |
| IP address | `203.0.113.10` |
| Country | `US` |
| ASN | `13335` |
| Header | `x-api-client` |
| User agent | `curl/8.0` |
| Query parameter | `preview=true` |
| Environment | `production` or `preview` |
See [Custom rules](/docs/security/custom-rules) for the full condition and
operator reference.
Actions [#actions]
| Action | Effect |
| --------------------------- | ------------------------------------------------------------------------ |
| **Log** | Records a firewall observation and continues. |
| **Deny** | Responds with 403 Forbidden. The request does not reach your deployment. |
| **Challenge** | Serves a browser proof-of-work checkpoint. |
| **Bypass attack challenge** | Skips project-wide Attack Mode for matching requests. |
| **Redirect** | Responds with an HTTP redirect to a Location you configure. |
Default behavior [#default-behavior]
When no project rule matches, the request continues unless another security
layer blocks or challenges it.
Firewall and application authorization [#firewall-and-application-authorization]
Firewall rules do not replace application authorization.
For example, an IP condition can reduce exposure of `/admin`, but the
application must still require authenticated and authorized users.
Related guides [#related-guides]
* [Custom rules](/docs/security/custom-rules)
* [IP rules](/docs/security/ip-rules)
* [Attack Mode](/docs/security/attack-mode)
* [Security evaluation order](/docs/security/request-chain)
* [Firewall observability](/docs/security/firewall-observability)
# Security
Easel protects every deployment with always-on platform protections and gives
you additional controls for managing application traffic and access.
Security on Easel has four layers:
* **Platform protections** identify and mitigate malicious or abusive traffic
automatically.
* **Firewall controls** let you log, block, challenge, redirect, or bypass
Attack Mode for requests using project-specific rules.
* **Access protection** (Deployment Protection) controls who may access
previews and other non-public deployments.
* **Workspace security** controls access to projects, settings, secrets, and
production operations.
These layers complement application-level security. Your application remains
responsible for authentication, authorization, input validation, session
management, and secure use of external services.
How requests are protected [#how-requests-are-protected]
A request may pass through several security layers before reaching your
application:
```text
Internet
↓
Platform protections
↓
Deployment protection
↓
Custom firewall rules
↓
Attack Mode
↓
CDN, routing, and cache
↓
Static assets or functions
```
The exact evaluation order matters because an earlier decision may prevent
later layers or application code from running.
See [Security evaluation order](/docs/security/request-chain).
Platform protections [#platform-protections]
Platform protections are operated by Easel and apply automatically.
They are designed to detect and mitigate:
* Network and application-layer attacks
* Request floods
* Known malicious or abusive sources
* Automated scanning and exploit attempts
* Suspicious traffic patterns
* Traffic intended to exhaust application resources
Platform protections do not require project-specific rules.
See [Platform protections](/docs/security/platform-protections).
Firewall controls [#firewall-controls]
The Easel Firewall lets you define project-specific traffic rules. Start with
[WAF rules](/docs/security/waf-rules) for an overview, then configure detailed
rules under Firewall, Custom rules, and IP rules.
Rules can evaluate request properties such as:
* Path
* Method
* IP address
* Country and ASN
* Header
* User agent
* Hostname
* Environment
A matching rule can log, deny, challenge, redirect, or bypass Attack Mode,
depending on the action you choose.
See [Firewall](/docs/security/firewall) and
[Custom rules](/docs/security/custom-rules).
Attack Mode [#attack-mode]
Attack Mode places an additional browser verification step in front of a
project during an active attack or sudden surge in abusive traffic.
It is intended as an emergency control, not as a replacement for application
authentication or carefully scoped firewall rules.
See [Attack Mode](/docs/security/attack-mode).
Access protection [#access-protection]
Access protection controls who can open a deployment before application code
runs. Easel provides this through Deployment Protection for Preview deployments,
branch URLs, unique deployment URLs, and other non-current deployments.
These controls are separate from the firewall:
* The firewall determines whether traffic is permitted at the request layer.
* Deployment protection determines whether the requester is authorized to
access the deployment.
See [Access protection](/docs/security/deployment-protection).
Security observability [#security-observability]
Security decisions appear alongside ordinary request activity.
You can use firewall events and request details to determine:
* Which action Easel took
* Which rule matched
* Whether the request reached application code
* Whether the request was challenged
* Which project and deployment received the request
See [Firewall observability](/docs/security/firewall-observability).
Shared responsibility [#shared-responsibility]
Easel secures the deployment platform and provides traffic and access controls.
You remain responsible for the security of your application and data.
See [Shared responsibility](/docs/security/shared-responsibility).
Related documentation [#related-documentation]
* [Platform protections](/docs/security/platform-protections)
* [Security evaluation order](/docs/security/request-chain)
* [WAF rules](/docs/security/waf-rules)
* [Firewall](/docs/security/firewall)
* [Custom rules](/docs/security/custom-rules)
* [IP rules](/docs/security/ip-rules)
* [Attack Mode](/docs/security/attack-mode)
* [Bot traffic](/docs/security/bots)
* [Firewall observability](/docs/security/firewall-observability)
* [Access protection](/docs/security/deployment-protection)
* [Security headers](/docs/security/security-headers)
* [Secrets](/docs/security/secrets)
* [Workspace security](/docs/security/workspace-security)
* [Security limits](/docs/security/limits)
* [Security troubleshooting](/docs/security/troubleshooting)
* [Report a vulnerability](/docs/security/report-a-vulnerability)
# IP rules
IP matching in the Easel Firewall uses the client IP address determined by
Easel.
Use IP conditions to:
* Restrict internal tools
* Allow trusted services past Attack Mode
* Block abusive networks
* Limit administrative routes
IP matching is configured as a condition on a
[custom firewall rule](/docs/security/custom-rules). There is no separate IP-list
product today.
Single addresses [#single-addresses]
Examples:
```text
203.0.113.10
2001:db8::10
```
IPv4 and IPv6 addresses are both supported as string values in IP conditions.
Matching operators [#matching-operators]
For the **IP / CIDR** condition type:
* **Equals** / **Does not equal** compare against the client IP string
* **Is any of** / **Is not any of** accept a list of values (one per line)
* String operators such as **Starts with** or **Contains** match the textual IP
form
Prefer exact equality or list membership over broad substring matches.
Client IP trust [#client-ip-trust]
Easel determines the client IP from its trusted edge connection.
Headers such as these are not trusted directly from arbitrary clients:
```text
X-Forwarded-For
X-Real-IP
CF-Connecting-IP
```
Easel honors forwarding headers only on its trusted edge path. That same client
IP feeds geo and ASN conditions.
Bypass Attack Mode for trusted IPs [#bypass-attack-mode-for-trusted-ips]
To exempt a monitoring service or office network from Attack Mode without
disabling platform protections:
```text
IP is any of
203.0.113.10
198.51.100.20
Action: Bypass attack challenge
```
**Bypass attack challenge** skips Attack Mode only. It does not skip platform
protections, deployment protection, or other custom rules above this rule in the
list.
Deny by IP [#deny-by-ip]
```text
IP equals 203.0.113.66
Action: Deny
```
Combine IP conditions with path or method conditions when you only need to
protect a subset of routes.
Dynamic clients [#dynamic-clients]
IP rules are a poor fit for users with frequently changing residential or mobile
addresses.
For human access to non-public deployments, prefer
[Deployment protection](/docs/security/deployment-protection) with workspace
sign-in.
Webhooks [#webhooks]
Webhook providers may publish IP ranges, but IP validation alone is often
insufficient.
Also verify:
* Request signatures
* Timestamps
* Replay protection
* Expected event types
* Request body integrity
Related guides [#related-guides]
* [Custom rules](/docs/security/custom-rules)
* [Firewall](/docs/security/firewall)
* [Attack Mode](/docs/security/attack-mode)
* [Security limits](/docs/security/limits)
# Security limits
These limits describe current platform behavior that affects security
configuration and challenge flows.
Attack Mode [#attack-mode]
| Limit | Value |
| ----------------------------- | ------------------------------------------ |
| Challenge response status | `429` |
| Verification endpoint | `POST /.well-known/easel-challenge/verify` |
| Session cookie | `easel_ch_pass` |
| Verification session lifetime | About 1 hour |
| Work-token lifetime | About 15 minutes |
Challenge difficulty is platform-managed and may change.
Deployment protection [#deployment-protection]
| Limit | Value |
| ---------------- | ------------ |
| Session cookie | `easel_dp` |
| Session lifetime | About 1 hour |
Request size [#request-size]
Large request bodies are rejected before they can exhaust edge or application
resources. The default maximum request body size is 10 MiB unless otherwise
configured for the platform.
Firewall rules [#firewall-rules]
Custom rules are ordered per project. There is no separate priority number beyond
list order.
Practical guidance:
* Prefer fewer, well-scoped rules over many overlapping ones
* Validate regex rules with **Log** before enforcing
* Combine path and method conditions before broad IP or country denies
Plan-specific quotas for rule count, IP lists, and log retention may be published
separately as product packaging evolves.
Geographic data [#geographic-data]
| Field | Support |
| ------------- | ------------------------------------ |
| Country | Supported in custom rules |
| Continent | Supported in custom rules |
| ASN | Supported in custom rules |
| Region / city | Not available as firewall conditions |
Geo and ASN data is powered by [IPLocate.io](https://www.iplocate.io)
(CC BY-SA 4.0). Accuracy can vary for VPNs, proxies, and mobile networks.
Unknown locations do not match equality conditions unless you account for that
explicitly.
Propagation [#propagation]
Firewall and Attack Mode configuration changes save on the project and propagate
to the edge after a short delay. You do not need to redeploy. Allow a brief
window before expecting every region to serve the latest rules.
Related guides [#related-guides]
* [Custom rules](/docs/security/custom-rules)
* [Attack Mode](/docs/security/attack-mode)
* [Firewall observability](/docs/security/firewall-observability)
# Platform protections
Platform protections identify and mitigate malicious or abusive traffic before
it can consume application resources.
They are managed by Easel and apply without project-specific configuration.
What platform protections cover [#what-platform-protections-cover]
Platform protections are designed to mitigate traffic such as:
* Network floods
* Application-layer request floods
* Known malicious sources
* Automated vulnerability scanning
* Repeated abusive behavior
* Suspicious request patterns
* Attempts to exhaust functions or origin resources
The specific detection systems and data sources used by Easel may change over
time. The customer-facing contract is the protection behavior, not a particular
internal implementation or third-party provider.
Automatic operation [#automatic-operation]
Platform protections are always active for supported Easel deployments.
They do not require:
* Custom firewall rules
* Attack Mode
* Application middleware
* Framework configuration
* Changes to application code
Project-specific firewall settings provide additional control but do not replace
the underlying platform protections.
What happens to blocked traffic [#what-happens-to-blocked-traffic]
Traffic rejected by a platform protection is stopped before it reaches static
output or invokes a function.
Blocked requests do not run your application code. They may still appear in
security and request analytics so you can investigate activity. Do not assume
blocked traffic is excluded from every usage meter unless a billing document
states that explicitly.
Visibility [#visibility]
When a platform protection stops a request, Easel exposes enough information for
you to understand the outcome without revealing sensitive detection details.
Useful signals include:
* Action taken (for example block, challenge, or throttle)
* Request ID and timestamp
* Path, method, and hostname
* Whether the decision came from platform protection rather than a custom rule
Easel does not expose internal provider names, private detection signatures, raw
reputation scores, or details that make evasion easier.
Customer overrides [#customer-overrides]
Custom firewall rules cannot disable platform protections.
The **Bypass attack challenge** action skips project-wide [Attack Mode](/docs/security/attack-mode)
only. It does not override platform blocks, deployment protection, or other
edge safety controls.
DDoS protection [#ddos-protection]
Platform protections help absorb network and HTTP request floods at the edge.
They are not interchangeable with:
* Custom firewall rules
* Attack Mode
* Application authentication
* Application-level rate limiting or quotas
No traffic-protection system can guarantee that every application remains
available during every attack. Protect expensive endpoints with authentication,
caching, validation, and carefully scoped firewall rules.
Limitations [#limitations]
Application design still matters. Protect expensive endpoints with:
* Authentication
* Authorization
* Caching
* Request validation
* Idempotency
* Application-level quotas
* Efficient database queries
* Carefully scoped firewall rules
Related guides [#related-guides]
* [Security evaluation order](/docs/security/request-chain)
* [Firewall](/docs/security/firewall)
* [Attack Mode](/docs/security/attack-mode)
* [Shared responsibility](/docs/security/shared-responsibility)
# Report a vulnerability
Report suspected vulnerabilities privately so the Easel security team can
investigate before public disclosure.
What to include [#what-to-include]
Include:
* A clear description
* Affected product or endpoint
* Reproduction steps
* Proof-of-concept requests or code
* Security impact
* Preconditions
* Relevant account, workspace, project, deployment, or request IDs
* Whether customer data may be affected
* Your preferred contact information
Do not include customer secrets or unrelated personal data.
Contact [#contact]
Email:
```text
security@easel.sh
```
Do not post vulnerabilities in community channels. Easel acknowledges reports
promptly and coordinates disclosure with you.
Research guidelines [#research-guidelines]
When testing:
* Stay within systems you are authorized to assess
* Avoid denial-of-service testing against production
* Do not access or exfiltrate customer data
* Do not use social engineering against Easel staff or customers
* Give Easel reasonable time to investigate before public disclosure
Account compromise [#account-compromise]
For suspected account compromise:
1. Revoke active sessions.
2. Rotate API tokens.
3. Rotate exposed application secrets.
4. Review workspace members.
5. Contact support or `security@easel.sh`.
Related guides [#related-guides]
* [Workspace security](/docs/security/workspace-security)
* [Secrets](/docs/security/secrets)
* [Shared responsibility](/docs/security/shared-responsibility)
# Security evaluation order
Security controls run in a defined order. An earlier decision may prevent later
controls or application code from running.
Request flow [#request-flow]
```text
Request received
↓
Platform protections
↓
Deployment protection
↓
Verified bot classification
↓
Custom firewall rules
↓
Attack Mode
↓
Cache and routing
↓
Static output or function
```
Platform protections run first and are not overridable by custom rules.
Deployment protection runs before custom firewall rules. Custom rules run before
Attack Mode, so a matching rule can deny, challenge, redirect, or bypass Attack
Mode before the project-wide challenge applies.
Why order matters [#why-order-matters]
Suppose a request matches both a custom deny rule and Attack Mode.
Because custom rules run first:
* A **Deny** rule stops the request with 403 before Attack Mode runs.
* A **Challenge** rule issues browser verification for that match.
* A **Bypass attack challenge** rule skips Attack Mode for that match.
* A **Log** rule records the match and continues evaluation.
Platform protections remain active regardless of custom-rule outcomes.
Terminal actions [#terminal-actions]
A terminal action ends evaluation for that layer and prevents the request from
reaching the application.
Terminal outcomes include:
* Platform block or throttle
* Custom rule **Deny**
* Custom rule **Redirect**
* Challenge response (from a custom rule or Attack Mode)
* Deployment protection sign-in response
A **Log** action records a match and continues. When no custom rule matches, the
request continues unless another security layer blocks or challenges it.
There is no separate **Allow** action that ends evaluation and skips later
layers. Use **Bypass attack challenge** when you need trusted traffic to skip
Attack Mode only.
Rule order [#rule-order]
Within a custom firewall configuration:
1. Active rules are evaluated from top to bottom.
2. The first matching rule wins.
3. Disabled rules are skipped.
4. Reordering rules changes which match applies first.
See [Custom rules](/docs/security/custom-rules).
Attack Mode [#attack-mode]
Attack Mode is a project-wide challenge that runs after custom firewall rules.
Custom rules can:
* Block traffic before the challenge
* Challenge only selected routes
* Bypass Attack Mode for matching traffic
* Redirect selected clients elsewhere
Verified bots may skip Attack Mode when **Allow verified bots** is enabled. See
[Bot traffic](/docs/security/bots).
Cache interaction [#cache-interaction]
Security controls run before cache lookup and origin routing.
A request must pass platform protections, deployment protection (when
applicable), custom rules, and Attack Mode before Easel serves cached content or
invokes your application. Short-circuit security responses are not stored as
ordinary cacheable application content.
Rewrites and internal requests [#rewrites-and-internal-requests]
Internal rewrites and routing decisions happen after security evaluation. Easel
does not re-run the full security chain for each internal rewrite hop.
External rewrite destinations and proxied origins receive traffic only after the
original client request has passed security controls.
Internal edge fetches used for platform operations can use a trusted bypass that
external clients cannot reproduce. Challenge verification for
`/.well-known/easel-challenge/*` is handled so verification can complete without
looping.
Request metadata [#request-metadata]
When a custom rule denies or fails a redirect, Easel may set response headers
such as:
* `X-Easel-Firewall-Action`
* `X-Easel-Firewall-Rule-Id`
Treat these as operational signals for debugging. Do not rely on client-supplied
copies of security headers as proof of identity. See
[Firewall observability](/docs/security/firewall-observability).
Related guides [#related-guides]
* [Platform protections](/docs/security/platform-protections)
* [Firewall](/docs/security/firewall)
* [Attack Mode](/docs/security/attack-mode)
* [Deployment protection](/docs/security/deployment-protection)
# Secrets
Secrets include API keys, database credentials, signing keys, and other values
that must not be committed to source control.
On Easel, secrets are stored as environment variables in project settings.
Environment scopes [#environment-scopes]
Use different secret values for:
* Preview
* Production
Preview deployments do not automatically receive Production secrets. You can
also set Preview branch overrides for branch-specific values.
See [Deployment environments](/docs/deployments/environments).
Encryption and access [#encryption-and-access]
Easel encrypts environment variable values at rest and restricts access through
workspace membership and project settings controls.
Sensitive variables are write-only in the dashboard after creation: you can
replace the value, but you cannot read it back or rename the key in a way that
exposes the prior secret.
Snapshots [#snapshots]
When a deployment is created, Easel snapshots the resolved variable values for
that environment. The build and runtime use that snapshot.
Changing variables later does not alter an existing deployment. Create a new
deployment to pick up updates.
Build access [#build-access]
Build commands may read environment variables required to compile the
application. Dependency installation scripts and build-time code may therefore
access build-scoped secrets.
Reduce risk by:
* Avoiding unnecessary secrets during builds
* Pinning dependencies
* Reviewing install scripts
* Separating build and runtime credentials
* Using least-privilege tokens
* Rotating exposed credentials
Runtime access [#runtime-access]
Functions receive the secrets available in the deployment’s snapshot for that
environment.
Logs [#logs]
Automatic redaction cannot catch every transformed or encoded value.
Applications must not log:
* Authorization headers
* Session cookies
* Full connection strings
* Private keys
* Access tokens
* Passwords
* Signed webhook secrets
Forks and Preview secrets [#forks-and-preview-secrets]
Treat Preview configuration as untrusted-input space:
* Keep Production secrets out of Preview variables
* Prefer Preview branch overrides only where needed
* Enable [deployment protection](/docs/security/deployment-protection) when
previews must not be public
Rotation [#rotation]
Rotate a secret when:
* A team member with access leaves
* It appears in source control or logs
* A third-party integration is compromised
* A credential reaches its scheduled rotation date
* Access scope changes
After updating a secret, create a new deployment so application code receives
the new value.
Deletion [#deletion]
Deleting a secret prevents future deployments from receiving it. Existing
deployments retain their previously resolved snapshot until they are replaced.
Related guides [#related-guides]
* [Deployment environments](/docs/deployments/environments)
* [Workspace security](/docs/security/workspace-security)
* [Shared responsibility](/docs/security/shared-responsibility)
# Security headers
HTTP response headers can reduce the impact of cross-site scripting, framing,
MIME confusion, and information leakage.
Easel may set infrastructure-level headers, but application-specific browser
policies remain your responsibility.
Content Security Policy [#content-security-policy]
Content Security Policy (CSP) restricts which resources a browser may load and
execute.
Example starting point:
```http
Content-Security-Policy: default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'
```
A real CSP must account for the application’s scripts, styles, images, APIs,
fonts, frames, and development tooling.
Roll out CSP carefully:
1. Begin with `Content-Security-Policy-Report-Only`.
2. Collect violation reports.
3. Remove unsafe dependencies.
4. Narrow allowed sources.
5. Enforce the policy.
Avoid adding broad values such as `*`, `'unsafe-inline'`, or `'unsafe-eval'`
without understanding the tradeoff.
HSTS [#hsts]
HTTP Strict Transport Security instructs browsers to use HTTPS.
Example:
```http
Strict-Transport-Security: max-age=31536000
```
Only add `includeSubDomains` when every subdomain supports HTTPS.
Only request preload after verifying the domain meets browser preload
requirements and the policy can be maintained.
See [HTTPS and TLS](/docs/cdn/https-and-tls).
Framing [#framing]
Prevent unauthorized framing with CSP:
```http
Content-Security-Policy: frame-ancestors 'none'
```
`X-Frame-Options` remains useful for older clients:
```http
X-Frame-Options: DENY
```
Use `SAMEORIGIN` or an explicit CSP allowlist when legitimate embedding is
required.
MIME sniffing [#mime-sniffing]
```http
X-Content-Type-Options: nosniff
```
This helps prevent browsers from interpreting a response as a different content
type.
Referrer policy [#referrer-policy]
Example:
```http
Referrer-Policy: strict-origin-when-cross-origin
```
Choose a policy based on analytics and privacy requirements.
Permissions policy [#permissions-policy]
Permissions Policy controls browser features such as camera, microphone, and
geolocation.
Example:
```http
Permissions-Policy: camera=(), microphone=(), geolocation=()
```
Framework configuration [#framework-configuration]
Configure headers using your framework’s supported mechanism (for example Next.js
`headers` in `next.config`).
See also [Request and response headers](/docs/cdn/headers) for platform headers
Easel may set on CDN responses.
Related guides [#related-guides]
* [Request and response headers](/docs/cdn/headers)
* [HTTPS and TLS](/docs/cdn/https-and-tls)
* [Shared responsibility](/docs/security/shared-responsibility)
# Shared responsibility
Security on Easel is shared between Easel and the customer.
Easel secures the platform and provides deployment, traffic, access, and
observability controls. Customers secure their application logic, identities,
data, dependencies, and external integrations.
Easel responsibilities [#easel-responsibilities]
Easel is responsible for:
* Operating the deployment platform
* Protecting the edge and control plane
* Isolating customer workloads
* Encrypting supported platform traffic
* Applying platform protections
* Enforcing configured firewall rules
* Protecting stored configuration according to platform controls
* Maintaining platform software
* Recording supported security events
* Responding to platform security incidents
Customer responsibilities [#customer-responsibilities]
Customers are responsible for:
* Application authentication
* Authorization and data isolation
* Input validation
* Secure session handling
* Dependency selection and updates
* Secret scope and rotation
* Database security
* External service permissions
* Application security headers
* Firewall-rule correctness
* Reviewing security events
* Legal and privacy obligations for application data
Shared areas [#shared-areas]
| Area | Easel | Customer |
| ----------------- | ------------------------------------ | -------------------------------------------- |
| Secrets | Secure storage and access controls | Choose, scope, and rotate values |
| Firewall | Execute rules reliably | Design and test rules |
| Deployments | Isolate and publish artifacts | Review source and dependencies |
| Logs | Collect and protect supported events | Avoid logging secrets and monitor events |
| Domains | Provide routing and TLS controls | Control DNS and domain ownership |
| Incident response | Respond to platform incidents | Respond to application and account incidents |
Application vulnerabilities [#application-vulnerabilities]
The firewall can reduce exposure but cannot correct insecure application logic.
Examples include:
* Broken authorization
* Injection flaws in application code
* Insecure direct object references
* Weak password-reset flows
* Cross-tenant data access
* Unsafe file uploads
* Vulnerable dependencies
Use secure development practices and application testing in addition to platform
controls.
Compliance [#compliance]
Using a hosting platform does not automatically make an application compliant.
Customers remain responsible for:
* Data classification
* Configuration
* Access policies
* Retention
* User consent
* Vendor management
* Required audits
* Application-specific controls
Related guides [#related-guides]
* [Platform protections](/docs/security/platform-protections)
* [Secrets](/docs/security/secrets)
* [Workspace security](/docs/security/workspace-security)
* [Report a vulnerability](/docs/security/report-a-vulnerability)
# Security troubleshooting
Start with the request ID and firewall event whenever available.
A legitimate request is blocked [#a-legitimate-request-is-blocked]
Check:
* Firewall action
* Rule ID and rule name
* Whether the decision came from a platform protection or custom rule
* Client IP
* Path and method
* Country and ASN
* Rule order
* Recent firewall changes
If a custom rule caused the block:
1. Disable or narrow the rule.
2. Confirm traffic recovers.
3. Recreate the issue with the **Log** action.
4. Refine the conditions.
5. Re-enable enforcement.
Do not create a broad **Bypass attack challenge** rule until you understand
which layers it does and does not skip.
A request is challenged unexpectedly [#a-request-is-challenged-unexpectedly]
Check whether:
* Attack Mode is enabled
* A custom rule uses **Challenge**
* The client lacks a valid verification cookie
* The request uses a different hostname or deployment
* Cookies or JavaScript are blocked
* A privacy tool removes verification state
An API or webhook stopped working [#an-api-or-webhook-stopped-working]
Attack Mode and browser challenges are usually incompatible with machine
clients.
Create a narrow **Bypass attack challenge** exemption based on strong signals
such as:
* Trusted IP range
* Dedicated webhook path
* Dedicated API hostname
Continue validating webhook signatures in application code.
A browser is stuck in a challenge loop [#a-browser-is-stuck-in-a-challenge-loop]
Check:
* JavaScript is enabled
* Cookies are allowed for the hostname
* The system clock is approximately correct
* The hostname remains consistent across redirects
* Multiple domains are not switching between unprotected and protected hosts
* CSP is not blocking challenge assets
Use the request ID from the challenge page when contacting support.
A verified bot is blocked [#a-verified-bot-is-blocked]
Check:
* The bot is genuinely verified
* Customer rules do not explicitly deny it
* The request comes from expected infrastructure
* **Allow verified bots** is enabled for Attack Mode
* Custom **Challenge** rules do not match the bot first
Do not allow a bot solely by user agent when stronger verification is available.
A rule does not match [#a-rule-does-not-match]
Check:
* The rule is active
* Rule order
* Exact path representation (normalized vs raw)
* Method
* Header spelling and key
* Case sensitivity
* Client IP source
* IPv4 versus IPv6
* Unknown geography
* Environment (`production` vs `preview`)
Use **Log** with one condition at a time to isolate the mismatch.
A rule matches too much traffic [#a-rule-matches-too-much-traffic]
Common causes include:
* `contains` used instead of `equals`
* Missing hostname condition
* Broad IP list
* Negated condition
* Incorrect AND/OR grouping
* Empty or missing header behavior
* Path normalization assumptions
Rule changes appear inconsistent by region [#rule-changes-appear-inconsistent-by-region]
Check:
* Change timestamp
* Edge region in request logs
* Whether older requests were already in flight
Firewall changes propagate after a short delay. Escalate behavior outside that
window with request IDs and regions.
Information to include with support [#information-to-include-with-support]
Include:
* Workspace and project
* Deployment ID
* Domain
* Request ID
* Approximate timestamp
* Client region
* Firewall action
* Rule ID
* Expected behavior
* Reproduction steps
Related guides [#related-guides]
* [Custom rules](/docs/security/custom-rules)
* [Attack Mode](/docs/security/attack-mode)
* [Firewall observability](/docs/security/firewall-observability)
* [Report a vulnerability](/docs/security/report-a-vulnerability)
# WAF rules
WAF rules let you match request attributes and choose an action before the
request reaches cache, static assets, or Functions.
What you can match [#what-you-can-match]
Depending on the rule type, matchers can include path, method, IP address,
country, ASN, header, user agent, hostname, and environment. See
[Firewall](/docs/security/firewall), [Custom rules](/docs/security/custom-rules),
and [IP rules](/docs/security/ip-rules).
Actions [#actions]
A matching rule can log, deny, challenge, redirect, or bypass Attack Mode,
depending on the action you configure.
Order and bypasses [#order-and-bypasses]
Earlier security decisions can prevent later layers from running. Test with
log-only rules when you need to observe matches without changing traffic. See
[Security evaluation order](/docs/security/request-chain).
Observability and limits [#observability-and-limits]
* [Firewall observability](/docs/security/firewall-observability)
* [Security limits](/docs/security/limits)
* [Security troubleshooting](/docs/security/troubleshooting)
* [Attack Mode](/docs/security/attack-mode)
* [Bot traffic](/docs/security/bots)
# Workspace security
Workspace security determines who can view projects and perform sensitive
actions.
Accounts [#accounts]
Protect Easel accounts with:
* Strong unique passwords, when password sign-in is enabled
* Secure OAuth account hygiene for connected identity providers
* Reviewed active sessions and revoked unused access
Sign-in options depend on your workspace configuration (for example GitHub
OAuth).
Roles [#roles]
Workspace roles follow least privilege. Easel uses these roles:
| Role | Typical access |
| ---------- | ------------------------------------------------------------- |
| **Owner** | Full workspace control, including billing and membership |
| **Admin** | Workspace and project administration |
| **Member** | Day-to-day project work such as deployments and configuration |
Owners and admins are managers for membership and workspace administration
tasks. Prefer inviting members with the least access they need.
Sensitive actions [#sensitive-actions]
Treat these as high-impact changes:
* Viewing or editing secrets
* Changing domains
* Enabling Attack Mode
* Editing firewall rules
* Promoting deployments
* Rolling back production
* Deleting projects
* Managing members and billing
* Creating or revoking API tokens
API tokens [#api-tokens]
Use API tokens with the narrowest practical scope, rotate them regularly, and
revoke tokens that are no longer needed. Avoid long-lived, unscoped personal
tokens for production automation.
Sessions [#sessions]
Revoke sessions you no longer recognize and rotate credentials if you suspect
account compromise. See
[Report a vulnerability](/docs/security/report-a-vulnerability) for security
contact details.
Related guides [#related-guides]
* [Secrets](/docs/security/secrets)
* [Deployment protection](/docs/security/deployment-protection)
* [Shared responsibility](/docs/security/shared-responsibility)
```
Framework build tools usually rewrite asset references automatically.
When deploying beneath a path prefix or using an external asset host, configure
the framework’s base path or asset prefix accordingly.
Examples include:
* Vite `base`
* Next.js `basePath` and `assetPrefix`
* Nuxt `app.baseURL`
* framework-specific public path configuration
See the relevant [framework guide](/docs/framework-guides).
Missing files [#missing-files]
A request for a file that does not exist in the selected deployment returns
`404` unless a routing rule or SPA fallback matches it.
Check:
* the build output contains the file
* the filename uses the correct capitalization
* the public path is correct
* the project root is configured correctly
* the output directory is correct
* the asset URL includes the expected base path
* the deployment being requested is the intended one
File paths are case-sensitive.
For example:
```text
/images/Logo.svg
```
and:
```text
/images/logo.svg
```
are different paths.
Large files [#large-files]
Static files remain subject to project and platform limits.
For large downloads, video, backups, or user-uploaded content, use object
storage rather than including the files in every application deployment.
Application deployments are best suited for assets that are:
* generated or versioned with the application
* required by the application interface
* reasonably sized
* updated through normal deployments
User-generated files should generally be stored separately from deployment
assets.
Deployment assets and object storage [#deployment-assets-and-object-storage]
Deployment assets are immutable files associated with an application release.
Object storage is intended for data that changes independently from application
deployments.
| Deployment assets | Object storage |
| --------------------------- | ----------------------------------------- |
| Created during the build | Created or updated at runtime |
| Versioned with a deployment | Managed independently |
| Read-only after deployment | Can support writes and deletes |
| Best for application files | Best for uploads and durable content |
| Released through a deploy | Updated through application logic or APIs |
Do not write user data to the deployment filesystem or a function’s local
filesystem.
Debugging static files [#debugging-static-files]
Inspect the response headers:
```bash
curl -I https://example.com/assets/app.js
```
Useful headers include:
```http
Content-Type: application/javascript; charset=utf-8
Cache-Control: public, max-age=31536000, immutable
Content-Encoding: br
X-Easel-Cache: HIT
```
A file returns 404 [#a-file-returns-404]
Verify that:
* it exists in the build output
* the output directory is configured correctly
* the URL uses the correct capitalization
* the framework base path matches the deployed URL
* a rewrite is not sending the request elsewhere
A file has the wrong content type [#a-file-has-the-wrong-content-type]
Check the extension and whether a custom header rule overrides `Content-Type`.
Avoid serving JavaScript or CSS through extensionless URLs unless the response
type is explicitly configured.
Visitors receive an old file [#visitors-receive-an-old-file]
Check whether the file uses a stable URL with a long browser cache lifetime.
For files that change, use content-hashed filenames or shorter browser caching.
Purging Easel’s CDN cache does not remove a file already stored in a visitor’s
browser.
An asset request invokes a function [#an-asset-request-invokes-a-function]
Check whether:
* a broad rewrite captures the asset path
* an SPA fallback also matches files
* the framework routes the path dynamically
* the file is absent from the static build output
Exclude asset directories from broad rewrites and middleware matchers where
appropriate.
Related documentation [#related-documentation]
* [CDN overview](/docs/cdn)
* [Caching](/docs/cdn/caching)
* [Revalidation and purging](/docs/cdn/revalidation)
* [Compression](/docs/cdn/compression)
* [Framework guides](/docs/framework-guides)
# CDN troubleshooting
Use this guide when a request is not being cached, stale content remains
visible, compression is missing, HTTPS is failing, or the response does not
follow the expected route.
Start by inspecting the response headers:
```bash
curl -I https://example.com/path
```
Useful headers include:
```http
X-Easel-Id: req_...
X-Easel-Cache: HIT
Cache-Control: public, max-age=0, must-revalidate
CDN-Cache-Control: public, s-maxage=300
Content-Encoding: br
```
`Age` may also appear on some responses. Treat `X-Easel-Cache` as the
authoritative cache-result header. Absence of `Age` is not an error.
Run the same request more than once when testing cache behavior:
```bash
curl -I https://example.com/path
curl -I https://example.com/path
```
A cacheable response commonly returns `MISS` on the first request and `HIT` on a
later request.
Identify the request path [#identify-the-request-path]
The fastest way to diagnose a CDN issue is to determine how Easel handled the
request.
| Observation | Likely path |
| ------------------------------ | --------------------------------------------------------------------- |
| Firewall or challenge response | Security rules completed the request |
| Redirect response | A routing or application redirect matched |
| `X-Easel-Cache: HIT` | A fresh cached response was served |
| `X-Easel-Cache: STALE` | A stale cached response was served while refreshing in the background |
| `X-Easel-Cache: MISS` | Easel retrieved or generated a new response |
| `X-Easel-Cache: BYPASS` | The request or response was not cacheable |
| No function log | The request may have been cached, static, redirected, or blocked |
| Function log present | Application compute handled the request |
Use `X-Easel-Id` to correlate the client response with Easel logs and
traces.
The response is not cached [#the-response-is-not-cached]
X-Easel-Cache is BYPASS [#x-easel-cache-is-bypass]
`BYPASS` means Easel did not attempt to store or reuse the response.
Check for these common causes:
* The request method is not `GET` or `HEAD`.
* The request contains `Authorization`.
* The request contains `Range`.
* The response contains `Set-Cookie`.
* The response is marked `private`.
* The response contains `no-store` or `no-cache`.
* The response does not include a positive shared-cache lifetime.
* The response status is not cacheable.
Inspect the relevant headers:
```bash
curl -I https://example.com/path
```
A basic cacheable policy looks like:
```http
Cache-Control: public, max-age=0, must-revalidate
CDN-Cache-Control: public, s-maxage=300
```
If the response includes:
```http
Set-Cookie: session=...
```
Easel bypasses shared caching.
Separate cookie-setting behavior from cacheable content when possible.
X-Easel-Cache is always MISS [#x-easel-cache-is-always-miss]
A repeated `MISS` means the request is eligible for cache processing, but Easel
is not finding a reusable matching entry.
Check that repeated requests use the same:
* hostname
* path
* query string
* deployment
* request method
* supported `Vary` values
These URLs may create different cache entries:
```text
/products
/products?page=1
/products?page=2
```
Also check whether:
* the TTL is too short
* the response changes its `Vary` header
* a deployment occurs between requests
* the route is being purged repeatedly
* the framework marks the route as dynamic
* the response exceeds a platform cache limit
The second request still returns MISS [#the-second-request-still-returns-miss]
Wait long enough for the first response to complete, then repeat the exact
request.
Use:
```bash
curl -sS -D - -o /dev/null https://example.com/path
curl -sS -D - -o /dev/null https://example.com/path
```
Confirm that the first response actually includes a positive CDN lifetime.
For example:
```http
CDN-Cache-Control: public, s-maxage=300
```
A browser extension, authentication layer, cookie, or upstream proxy may also
alter otherwise identical requests.
The response has Cache-Control, but is not cached [#the-response-has-cache-control-but-is-not-cached]
Easel uses cache headers in this order:
1. `Vercel-CDN-Cache-Control`
2. `CDN-Cache-Control`
3. `Cache-Control`
A higher-priority header may override the policy you are inspecting.
For example:
```http
Vercel-CDN-Cache-Control: no-store
CDN-Cache-Control: public, s-maxage=3600
```
The response is not cached because the Vercel-compatible header takes
precedence.
Inspect all three headers together.
Cached content is stale [#cached-content-is-stale]
Content remains old after a purge [#content-remains-old-after-a-purge]
Check that:
* the purge targeted the correct project
* the correct environment was selected
* the tag or URL exactly matches the cached entry
* the browser is not serving its own cached copy
* the underlying application data was updated before the purge
* another cache layer still contains old data
* the route regenerated successfully after invalidation
A CDN purge cannot remove a response already stored in the visitor’s browser.
Compare:
```http
Cache-Control: public, max-age=3600
CDN-Cache-Control: public, s-maxage=86400
```
The browser may reuse its copy for one hour even after Easel’s shared cache is
purged.
For content that must reflect CDN invalidation quickly, use:
```http
Cache-Control: public, max-age=0, must-revalidate
CDN-Cache-Control: public, s-maxage=86400
```
A page regenerates with old data [#a-page-regenerates-with-old-data]
The CDN response may have been invalidated while the application continued using
stale Runtime Cache or framework data-cache entries.
Use a shared cache tag across:
* the rendered HTTP response
* Runtime Cache values
* framework data-cache entries
* related routes
Alternatively, invalidate each layer explicitly.
Update the source of truth before initiating invalidation:
```text
1. Update the database or content source
2. Confirm the update succeeded
3. Purge the relevant tag or route
4. Allow the next request to regenerate content
```
Purging before the update completes can cause the route to regenerate using old
data.
A purge affects less content than expected [#a-purge-affects-less-content-than-expected]
A URL purge targets one cache key. It does not automatically invalidate related
URLs.
Purging:
```text
/products/123
```
does not necessarily purge:
```text
/products
/api/products/123
/products/123?currency=USD
```
Use a shared tag such as:
```http
Cache-Tag: products product:123
```
when one data change affects multiple representations.
Browser caching differs from CDN caching [#browser-caching-differs-from-cdn-caching]
The browser and Easel can use different cache lifetimes.
```http
Cache-Control: public, max-age=60
CDN-Cache-Control: public, s-maxage=3600
```
This means:
* the browser may reuse its copy for 60 seconds
* Easel may reuse its copy for one hour
When debugging, test with `curl` to avoid relying on the browser’s local cache.
You can also disable the browser cache temporarily in browser developer tools.
Do not use a cache-busting query parameter as the first diagnostic step. A
changed query string may create a different CDN cache key and hide the original
problem.
A static file returns 404 [#a-static-file-returns-404]
Check that:
* the file exists in the framework’s public or output directory
* the filename uses the correct letter casing
* the build includes the file
* the route does not conflict with a rewrite or function
* the configured root directory is correct
* the expected deployment is receiving the request
Production filesystems are case-sensitive.
For example:
```text
/logo.svg
/Logo.svg
```
may refer to different files.
Inspect the build output and preview deployment before promoting the change to
production.
An old static asset is still being served [#an-old-static-asset-is-still-being-served]
Confirm that the page references the current asset URL.
Content-hashed files should receive a new filename when their contents change:
```text
/assets/app.9f3ac21.js
/assets/app.32bca78.js
```
If HTML still references the old asset, the problem may be stale HTML rather
than stale asset storage.
Check:
* the HTML cache policy
* deployment promotion status
* service-worker caches
* browser caches
* hardcoded asset URLs
* upstream proxies
A service worker can continue serving old files independently of Easel’s CDN
cache.
A redirect is unexpected [#a-redirect-is-unexpected]
Inspect the response without following redirects:
```bash
curl -I https://example.com/path
```
Look for:
```http
HTTP/2 301
Location: https://example.com/other-path
```
Possible redirect sources include:
* HTTP-to-HTTPS enforcement
* project routing rules
* framework configuration
* middleware
* application code
* canonical-domain redirects
* an upstream proxy
Follow the complete redirect chain with:
```bash
curl -IL https://example.com/path
```
Review each `Location` header to identify where the chain begins.
The site is stuck in a redirect loop [#the-site-is-stuck-in-a-redirect-loop]
Redirect loops commonly happen when two layers independently enforce the same
rule.
Check for combinations such as:
* Easel and an upstream proxy both forcing HTTPS
* apex and `www` redirects pointing at each other
* middleware redirecting back to its own matcher
* application code disagreeing with forwarded protocol headers
* locale redirects repeatedly adding or removing a path segment
Use:
```bash
curl -IL --max-redirs 10 https://example.com
```
Inspect each hop.
When a proxy sits in front of Easel, ensure that it connects to Easel over HTTPS
and preserves the original protocol correctly.
A firewall blocks a valid request [#a-firewall-blocks-a-valid-request]
Use the returned request ID and any firewall diagnostic headers to inspect the
matching security event.
Possible causes include:
* a custom WAF rule
* managed-rule detection
* an IP or network restriction
* rate limiting
* Attack Mode
* bot or abuse detection
* an upstream proxy causing many visitors to share one apparent IP
Reproduce the request with the same:
* URL
* method
* headers
* body
* authentication state
Do not disable broad security protections permanently to resolve one false
positive. Narrow the matching rule or add a scoped exception.
See [Security](/docs/security).
A function was not invoked [#a-function-was-not-invoked]
The request may have completed before reaching application compute.
Common causes include:
* a fresh CDN cache hit
* a static deployment asset
* a redirect
* a firewall block
* a challenge response
* middleware returning a response
* the request reaching a different route than expected
Check:
```http
X-Easel-Cache
X-Easel-Id
```
Then inspect project request logs rather than only function logs.
A missing function invocation does not necessarily indicate that Easel dropped
the request.
A function runs when a cache hit was expected [#a-function-runs-when-a-cache-hit-was-expected]
Check that:
* the response includes a positive CDN TTL
* the route does not set cookies
* the request does not include authentication
* query strings are identical
* `Vary` values are stable
* no purge occurs between requests
* the framework has not opted the route into dynamic rendering
* middleware does not alter the cache key or response
* the response status is cacheable
For Next.js, request-time APIs such as cookies or headers can make a route
dynamic depending on the framework version and route configuration.
See the relevant [framework guide](/docs/framework-guides).
Compression is missing [#compression-is-missing]
Inspect the request and response:
```bash
curl -I \
-H 'Accept-Encoding: br, gzip' \
https://example.com/app.js
```
Look for:
```http
Content-Encoding: br
Vary: Accept-Encoding
```
Compression may not be applied when:
* the client does not advertise Brotli or gzip
* the response type is not compressible
* the response is below the minimum size
* the response is already encoded
* compression would not reduce the response size
* the request is a range request
* the response does not include a recognized `Content-Type`
* streaming behavior prevents buffering or transformation
Compare the compressed and uncompressed response sizes:
```bash
curl -sS \
-H 'Accept-Encoding: identity' \
-o /dev/null \
-w '%{size_download}\n' \
https://example.com/app.js
curl -sS \
--compressed \
-o /dev/null \
-w '%{size_download}\n' \
https://example.com/app.js
```
See [Compression](/docs/cdn/compression).
HTTPS is not active [#https-is-not-active]
Check the custom-domain status in Easel.
Common causes include:
* missing DNS records
* conflicting DNS records
* DNS changes that have not propagated
* a restrictive CAA record
* a proxied DNS record
* DNSSEC errors
* the domain pointing to another project
* certificate issuance rate limits
Verify DNS independently:
```bash
dig example.com
dig CNAME www.example.com
dig CAA example.com
```
Use the exact DNS values displayed in Easel.
Do not repeatedly remove and re-add the domain while DNS is still propagating.
The browser shows a certificate warning [#the-browser-shows-a-certificate-warning]
Confirm that:
* the exact hostname is configured
* certificate provisioning is complete
* DNS points to the correct Easel project
* an upstream proxy is not serving another certificate
* the device clock is correct
* local security software is not intercepting TLS
Inspect the certificate:
```bash
openssl s_client \
-connect example.com:443 \
-servername example.com
```
A certificate for `example.com` does not automatically cover every subdomain.
See [HTTPS and TLS](/docs/cdn/https-and-tls).
HTTP does not redirect to HTTPS [#http-does-not-redirect-to-https]
Check:
```bash
curl -I http://example.com
```
The response should redirect to the HTTPS URL.
If it does not, confirm that:
* the hostname is active
* the request reaches Easel
* an upstream proxy is not intercepting HTTP
* no conflicting routing rule handles the request first
A custom response header is missing [#a-custom-response-header-is-missing]
The header may have been:
* overwritten by a higher-priority routing rule
* removed by framework behavior
* replaced by Easel because it uses a reserved name
* treated as hop-by-hop
* removed by an upstream proxy
* rejected because of a size limit
* added only to a route that did not handle the request
Avoid custom headers in the reserved `X-Easel-*` namespace.
Use:
```http
X-My-App-Version: 42
```
instead of:
```http
X-Easel-App-Version: 42
```
Inspect the complete redirect chain because headers on an intermediate response
do not necessarily appear on the final destination.
A request metadata header is missing [#a-request-metadata-header-is-missing]
Some headers are available only on deployed requests and do not appear during
local development.
Also check whether:
* the route reached application compute
* the framework exposes the original request headers
* an upstream proxy changed the request
* the header is supported for that route type
* the documented header name is correct
Do not depend on undocumented internal headers.
See [Request and response headers](/docs/cdn/headers).
Client IP or country appears incorrect [#client-ip-or-country-appears-incorrect]
IP geolocation is approximate.
Unexpected values may also occur when:
* a VPN is in use
* a corporate gateway sends the request
* a mobile carrier proxies traffic
* another CDN or reverse proxy sits in front of Easel
* the application reads an untrusted forwarded header
* the IP database has not yet reflected a recent allocation
Use the documented trusted Easel header rather than arbitrary client-supplied
`X-Forwarded-For` values.
Do not use IP geolocation as the only signal for high-impact access or
compliance decisions.
Preview and production behave differently [#preview-and-production-behave-differently]
Check for differences in:
* environment variables
* custom domains
* root directories
* build commands
* framework versions
* routing rules
* firewall policies
* function placement relative to databases
* cache state
* preview access protection
* database branches or external services
Preview and production deployments have separate URLs and deployment contexts. A
warm production cache does not imply that the preview cache is also warm.
Reproduce the issue using the preview deployment’s exact hostname.
A change works locally but not after deployment [#a-change-works-locally-but-not-after-deployment]
Production builds can expose differences involving:
* case-sensitive paths
* missing environment variables
* build-time versus runtime variables
* unsupported filesystem assumptions
* native dependencies
* framework adapter output
* route generation
* static versus dynamic rendering
* Node.js versions
* external network access
Inspect the build logs first, then use the request ID to inspect runtime logs.
Do not assume that a local development server has the same caching, routing, or
security behavior as a deployed preview.
An external rewrite fails [#an-external-rewrite-fails]
Check that:
* the destination URL uses the correct protocol
* the origin hostname resolves publicly
* the origin accepts requests from Easel
* the origin certificate is valid
* required authentication headers are present
* the rewrite preserves the required path and query string
* the origin is not redirecting back to the Easel URL
* an upstream firewall is not rejecting Easel traffic
Test the origin directly where appropriate:
```bash
curl -I https://origin.example.net/path
```
Then test through Easel:
```bash
curl -I https://example.com/proxied-path
```
Compare the status, `Location`, cache, and request headers.
A response is unexpectedly personalized [#a-response-is-unexpectedly-personalized]
A shared cached response should not contain visitor-specific data.
Immediately check for:
* missing `private` or `no-store`
* authentication performed without cache bypass
* personalization based on cookies not represented in the cache key
* unsupported or incorrect `Vary`
* middleware adding user-specific content before caching
* application state leaking between requests
User-specific responses should generally return:
```http
Cache-Control: private, no-store
```
Do not rely on short TTLs to protect private content.
Purge the affected content and correct the cache policy before restoring the
route.
A response is unexpectedly slow [#a-response-is-unexpectedly-slow]
Determine whether the request is:
* a cache hit
* a cache miss
* a bypass
* a static asset
* a dynamic function
* an external-origin request
Start with:
```bash
curl -sS -D - -o /dev/null \
-w 'connect=%{time_connect} starttransfer=%{time_starttransfer} total=%{time_total}\n' \
https://example.com/path
```
A slow cache hit points toward network conditions, response size, or connection
setup.
A slow miss may involve:
* function startup
* application execution
* database latency
* external API latency
* distance between the CDN edge and US East compute
* response streaming
* cache regeneration
Use Easel traces to separate platform time from application and downstream-service
time.
Collecting information for support [#collecting-information-for-support]
Include the following when reporting a CDN issue:
* project name or ID
* deployment ID
* affected hostname
* complete URL
* approximate request time and timezone
* request method
* response status
* `X-Easel-Id`
* `X-Easel-Cache`
* relevant cache-control headers
* whether the issue affects preview, production, or both
* reproduction steps
* whether an upstream proxy is present
Do not send:
* session cookies
* authorization tokens
* private API keys
* password-reset links
* unredacted personal data
A reproducible request is especially useful:
```bash
curl -I https://example.com/path
```
Include safe request headers only when they are required to reproduce the
behavior.
Related documentation [#related-documentation]
* [CDN overview](/docs/cdn)
* [Caching](/docs/cdn/caching)
* [Revalidation and purging](/docs/cdn/revalidation)
* [Static files](/docs/cdn/static-files)
* [Compression](/docs/cdn/compression)
* [HTTPS and TLS](/docs/cdn/https-and-tls)
* [Request and response headers](/docs/cdn/headers)
* [Security](/docs/security)
* [Framework guides](/docs/framework-guides)
# Authenticate the CLI
Authenticate the CLI so platform commands can access your workspace.
Log in [#log-in]
Run `easel login` to open a browser session against [app.easel.sh](https://app.easel.sh). After you approve access, the CLI saves a token locally and prints the signed-in user and active workspace.
```bash
easel login
easel whoami
```
Tokens created by login include deploy permissions (`deployments:create`, `files:write`). If you logged in before those scopes existed, run `easel logout && easel login` once.
Token resolution [#token-resolution]
Token resolution order is:
1. `--token` / `-t` on the command line
2. The `EASEL_TOKEN` environment variable
3. The token saved by `easel login`
For CI or non-interactive shells, set `EASEL_TOKEN` instead of using browser login:
```bash
export EASEL_TOKEN="your_access_token_here"
easel whoami --format json
```
Log out [#log-out]
Remove saved credentials with:
```bash
easel logout
```
Next steps [#next-steps]
```
Nuxt Image can be added with:
```bash
npx nuxt module add image
```
Then use `