Adapter type signature
An adapter has the type signature: (opts: any) => import('@sveltejs/kit').Adapter. It takes options as an argument and returns an Adapter.
Svelte · SvelteKit · all subjects
adapters and deployment
195 notes in this subject, read out of this brain and free to use. This is page 1 of 4.
Adapter purpose
Adapters are small plugins that take the built SvelteKit app as input and generate output for deployment to specific platforms.
Community adapters exist
Additional community-provided adapters exist for platforms beyond the official ones documented in the SvelteKit docs.
Adapter configuration location
The adapter is specified in the svelte.config.js file under the kit.adapter property.
Platform-specific context via RequestEvent
Adapters may have access to additional platform-specific information about requests. This information is passed to the RequestEvent used in hooks and server routes as the platform property. The specific properties available depend on each adapter's documentation.
Official adapters list
SvelteKit provides official adapters for: @sveltejs/adapter-cloudflare for Cloudflare Workers and Cloudflare Pages; @sveltejs/adapter-netlify for Netlify; @sveltejs/adapter-node for Node servers; @sveltejs/adapter-static for static site generation (SSG); @sveltejs/adapter-vercel for Vercel.
Cloudflare Workers size limits
Cloudflare Workers has size limits that the bundled SvelteKit server must not exceed after minification. If hitting this limit, reduce worker size by only importing large libraries on the client side.
Typing Cloudflare Workers bindings in SvelteKit
Install @cloudflare/workers-types and declare types in src/app.d.ts by defining the Platform interface in the App namespace with env property containing your KV and Durable Object namespaces.
adapter-cloudflare-workers deprecation
The adapter-cloudflare-workers has been deprecated in favour of adapter-cloudflare. Users should use adapter-cloudflare to deploy to Cloudflare Workers with Static Assets since Cloudflare Workers Sites will be deprecated in favour of it.
adapter-cloudflare-workers installation
Install adapter-cloudflare-workers with npm i -D @sveltejs/adapter-cloudflare-workers, then import it in svelte.config.js and add it to the kit.adapter configuration.
File system access in Cloudflare Workers
The fs module cannot be used in Cloudflare Workers. Routes that require file system access must be prerendered instead.
Local testing platform emulation for adapter-cloudflare-workers
Cloudflare Workers specific values in the platform property are emulated during dev and preview modes. Local bindings are created from the Wrangler configuration file and populate platform.env during development and preview. Use the platformProxy adapter option to customize binding preferences.
Wrangler configuration file structure for adapter-cloudflare-workers
The Wrangler configuration file (wrangler.jsonc) should contain: name (your service name), account_id (found via wrangler whoami or Cloudflare dashboard), main (path to worker file, typically ./.cloudflare/worker.js), site.bucket (path to static assets, typically ./.cloudflare/public), build.command (npm run build), and compatibility_date (e.g., 2021-11-12).
Testing adapter-cloudflare-workers builds
For testing the build locally, use Wrangler version 4. After running npm run build, run wrangler dev to test locally.
File system access in Netlify deployments
The fs module cannot be used in edge deployments. In serverless deployments, fs can be used but files are not copied from the project into the deployment. Instead, use the read function from $app/server to access files, which works in both serverless and edge deployments. Alternatively, prerender the routes in question.
Node version on Netlify
New projects on Netlify will use the current Node LTS version by default. Projects created earlier may be stuck on an older version. See the Netlify documentation for details on manually specifying a current Node version.
Netlify Functions with SvelteKit
SvelteKit endpoints are hosted as Netlify Functions when using adapter-netlify. Additional Netlify functions can be created by creating a directory for them and adding configuration to netlify.toml under the [functions] section with a directory property.
Netlify _headers and _redirects files
The Netlify-specific _headers and _redirects files can be used for static asset responses by placing them in the project root folder. The [[redirects]] syntax can also be used in netlify.toml.
netlify.toml configuration
A netlify.toml file must be present in the project root to configure the build. It should contain build settings including command and publish directory. The publish directory determines where static assets are written. If netlify.toml or the build.publish value is missing, a default value of 'build' is used.
Accessing Netlify context in server endpoints
Netlify function handlers provide additional context including Netlify Identity information. This context is accessible via the event.platform.context field inside hooks and +page.server or +layout.server endpoints. These are serverless functions when edge is false or edge functions when edge is true.
Netlify Edge Functions with SvelteKit
SvelteKit supports Netlify Edge Functions. When edge: true is passed to the adapter, server-side rendering happens in a Deno-based edge function deployed close to the site visitor. When edge: false (the default), the site deploys to Node-based Netlify Functions.
Netlify Forms with SvelteKit
To use Netlify Forms with SvelteKit: create an HTML form in a route like /routes/contact/+page.svelte with a hidden form-name input element; prerender the page by adding export const prerender = true or setting kit.prerender.force: true; if the form has a custom success action like action='/success', ensure the corresponding /routes/success/+page.svelte exists and is prerendered.
adapter-netlify installation and setup
Install adapter-netlify with `npm i -D @sveltejs/adapter-netlify`. Import it in `svelte.config.js` and add it to the `kit.adapter` property. The adapter-netlify is installed by default when using adapter-auto.
adapter-netlify configuration options
The adapter-netlify function accepts the following options: edge (boolean, default false) - if true, creates a Netlify Edge Function using Deno rather than Node-based functions; split (boolean, default false) - if true, splits the app into multiple functions instead of creating a single one for the entire app. The split option cannot be used when edge is true.
Adapter adapt method signature
The adapt method is an async function that receives a builder parameter. It is required and contains the main adapter implementation logic.
Adapter name property
The name property is a string identifier for the adapter, typically formatted as 'adapter-package-name'. This property is required.
Adapter object structure and required properties
An adapter must export a default function that returns an Adapter object. The Adapter object requires two properties: name (a string like 'adapter-package-name') and adapt (an async method). The properties emulate and supports are optional.
builder.getServerDirectory method
builder.getServerDirectory() returns the path to the server directory from which the Server should be imported as builder.getServerDirectory()/index.js.
builder.generateManifest method
builder.generateManifest({ relativePath }) generates a manifest for instantiating the app, taking a relativePath option.
Adapter platform option in server.respond
Platform-specific information should be exposed to SvelteKit via the platform option passed to server.respond(), which becomes accessible as event.platform in load functions and route handlers.
builder.writePrerendered method
builder.writePrerendered is a method used within the adapt function to write SvelteKit's prerendered output.
builder.writeServer method
builder.writeServer is a method used within the adapt function to write SvelteKit's server output.
builder.writeClient method
builder.writeClient is a method used within the adapt function to write SvelteKit's client output.
Adapter output directory structure
Adapter output should be placed under the build/ directory where possible, with intermediate output placed under .svelte-kit/[adapter-name].
Adapter adapt method responsibilities
The adapt method should: clear the build directory; write SvelteKit output using builder.writeClient, builder.writeServer, and builder.writePrerendered; output code that imports Server from builder.getServerDirectory()/index.js; instantiate the app with a manifest generated by builder.generateManifest({ relativePath }); listen for requests and convert them to standard Request objects; call server.respond(request, { getClientAddress }) to generate a Response; expose platform-specific information via the platform option; globally shim fetch if necessary using @sveltejs/kit/node/polyfills for platforms using undici; bundle output to avoid installing dependencies on the target platform; and put static files and generated JS/CSS in the correct location.
Adapter supports property
The supports property is optional and contains two methods: read and instrumentation. The read method takes config and route and returns true/false or throws an error describing if the route can use read from $app/server in production. The instrumentation method returns true/false or throws an error describing if the adapter supports loading instrumentation.server.js.
Adapter emulate method
The emulate method is optional and async. It returns an object with a platform async function that takes config and prerender parameters. The object returned from the platform function becomes event.platform during dev, build, and preview, and must match the shape of App.Platform.
server.respond method signature
server.respond(request, { getClientAddress }) is called to generate a Response from a Request object. It accepts a request parameter and an options object containing getClientAddress.
GitHub Pages .nojekyll file
If you're not using GitHub actions to deploy your site to GitHub Pages (for example, pushing the built site to its own repo), add an empty .nojekyll file in your static directory to prevent Jekyll from interfering with the site.
GitHub Pages adapter-static configuration
When building for GitHub Pages, if your repo name is not equivalent to your-username.github.io, make sure to update config.kit.paths.base to match your repo name. The site will be served from https://your-username.github.io/your-repo-name rather than from the root. You should also set the fallback option to '404.html' to generate a fallback page to replace GitHub Pages' default 404 page.
adapter-static partial prerendering
If you'd like to prerender only some pages and dynamically server-render others, you will need to use a different adapter together with the prerender option (instead of using adapter-static alone).
adapter-static for single page apps (SPA)
To create a single page app (SPA) with adapter-static, you must specify the name of the fallback page in the adapter options (commonly '200.html'). This fallback page is used as the entry point for URLs that have not been prerendered. You should avoid index.html where possible to avoid conflicting with a prerendered homepage.
adapter-static zero-config support
Some platforms have zero-config support for adapter-static, meaning you should omit the adapter options so that adapter-static can provide the optimal configuration. Vercel is a platform with zero-config support.
ssr option must be enabled for adapter-static
When using adapter-static, you must ensure SvelteKit's ssr option is not set to false. Otherwise, prerendering will save an empty 'shell' page instead of the fully rendered content.
trailingSlash configuration for adapter-static
When using adapter-static, you must ensure SvelteKit's trailingSlash option is set appropriately for your environment. If your host does not render /a.html upon receiving a request for /a, you need to set trailingSlash: 'always' in your root layout to create /a/index.html instead.
adapter-static strict mode
The strict option in adapter-static defaults to true and checks that either all pages and endpoints of your app were prerendered, or you have the fallback option set. This check prevents accidentally publishing an app where some parts are not accessible. Set strict to false to disable this check if you know it is safe (for example when a certain page only exists conditionally).
adapter-static options
adapter-static accepts the following options: pages (directory to write prerendered pages to, defaults to 'build'), assets (directory to write static assets to, defaults to the value of pages), fallback (name of fallback page for SPA mode, e.g. '200.html', commonly used with deployment platforms), precompress (if true, precompresses files with brotli and gzip to generate .br and .gz files, defaults to false), strict (validates that all pages and endpoints were prerendered or fallback is set, defaults to true).
adapter-static for static site generation
To use SvelteKit as a static site generator (SSG), use adapter-static. This will prerender your entire site as a collection of static files. Install with npm i -D @sveltejs/adapter-static, then add the adapter to your svelte.config.js.
Apache configuration for SPA fallback routing
To run an SPA on Apache, add a static/.htaccess file with mod_rewrite rules. The configuration should enable RewriteEngine, set RewriteBase to /, exclude the fallback page itself and existing files/directories from rewriting, and route all other requests to the fallback page (e.g., /200.html).
Fallback page uses absolute asset paths
The fallback page will always contain absolute asset paths (beginning with / rather than .) regardless of the value of paths.relative configuration, since it is used to respond to requests for arbitrary paths.
Fallback page naming considerations
The specific fallback page filename depends on the hosting platform. Examples include 200.html for Surge. Avoid using index.html if possible as it may conflict with prerendering.
Fallback page behavior
The fallback page is an HTML page created by SvelteKit from your page template (e.g. app.html) that loads your app and navigates to the correct route. It will be served for requests that don't correspond to static assets or prerendered pages.
adapter-static configuration for SPA
If your SvelteKit app has no server-side logic (no +page.server.js, +layout.server.js, or +server.js files), use adapter-static to create an SPA. Install it with 'npm i -D @sveltejs/adapter-static' and configure it in svelte.config.js with the fallback option, specifying a fallback page name like '200.html'. The exact fallback filename may differ depending on the hosting platform.
Disable SSR for SPA pages
Set export const ssr = false in src/routes/+layout.js to disable server-side rendering for pages you don't want to prerender. These pages will be served via the fallback page. You should opt back into prerendering individual pages and directories where possible.
Mitigate SPA mode drawbacks with prerendering
To avoid SPA mode drawbacks, prerender as many pages as possible, especially the homepage. If you can prerender all pages, use static site generation instead of SPA mode. Otherwise, strongly consider using an adapter that supports server-side rendering.
SPA mode performance drawbacks
SPA mode has significant negative performance impacts. It forces multiple network round trips (for the blank HTML document, then for JavaScript, and then for data needed for the page) before content can be shown. This delays startup, especially on mobile devices with high latency. It also harms SEO by causing performance downgrades and Core Web Vitals failures, excludes search engines that don't render JavaScript, and makes apps inaccessible if JavaScript fails or is disabled.
SPA mode definition and fallback page
A SvelteKit app can be turned into a fully client-rendered single-page app (SPA) by specifying a fallback page. This page will be served for any URLs that cannot be served by other means such as returning a prerendered page.
Prerender individual pages in SPA mode
To prerender specific pages in SPA mode, set both export const prerender = true and export const ssr = true in the page's +page.js file. This allows the page to be server-rendered only during the build process to output an HTML file that can be served from any static web host, without needing a Node server.
adapter-vercel installation and configuration
Install @sveltejs/adapter-vercel with npm i -D @sveltejs/adapter-vercel. Add it to svelte.config.js by importing it and passing it to kit.adapter, wrapping it in a call to adapter() where options can be specified.
adapter-vercel deployment configuration via page options
Deployment configuration can be specified through export const config in +server.js, +page(.server).js, and +layout(.server).js files. Configuration set in a layout applies to all routes beneath that layout unless overridden at a more granular level.