Skip to main content

Writing adapters

If an adapter for your preferred environment doesn’t yet exist, you can build your own. We recommend looking at the source for an adapter to a platform similar to yours and copying it as a starting point.

Adapter packages implement the following API, which creates an Adapter:

/** @param {AdapterSpecificOptions} options */
export default function (options) {
	/** @type {import('@sveltejs/kit').Adapter} */
	const adapter = {
		name: 'adapter-package-name',
		async adapt(builder) {
			// adapter implementation
		},
		async emulate() {
			return {
				async platform({ config, prerender }) {
					// the returned object becomes `event.platform` during dev, build and
					// preview. Its shape is that of `App.Platform`
				}
			}
		},
		supports: {
			read: ({ config, route }) => {
				// Return `true` if the route with the given `config` can use `read`
				// from `$app/server` in production, return `false` if it can't.
				// Or throw a descriptive error describing how to configure the deployment
			},
			instrumentation: () => {
				// Return `true` if this adapter supports loading `instrumentation.server.js`.
				// Return `false if it can't, or throw a descriptive error.
			}
		},
		dev: {
			respond(request, { getClientAddress, resolve }) {
				// during `vite dev`, render the request in your platform's runtime,
				// or call `resolve` to render it in Node as usual
				return resolve(request);
			}
		},
		vite: {
			plugins: {
				// add plugins here to integrate with Vite
				pre: [],
				post: []
			}
		}
	};

	return adapter;
}

Of these, name and adapt are required. emulate, dev, vite, and supports are optional.

Within the adapt method, there are a number of things that an adapter should do:

  • Clear out the build directory
  • Write SvelteKit output with builder.writeClient, builder.writeServer, and builder.writePrerendered
  • Output code that:
    • Imports a server instance generated by ${builder.generateServerInstance()}
    • Runs await server.init({ env, read })
    • Listens for requests from the platform, converts them to a standard Request if necessary, calls the server.respond(request, { getClientAddress }) function to generate a Response and responds with it
    • expose any platform-specific information to SvelteKit via the platform option passed to server.respond
  • Bundle the output to avoid needing to install dependencies on the target platform, if necessary
  • Put the user’s static files and the generated JS/CSS in the correct location for the target platform

Where possible, we recommend putting the adapter output under the build/ directory with any intermediate output placed under .svelte-kit/[adapter-name].

Rendering in your platform’s runtime during development

By default, vite dev renders requests in Node. If your platform’s runtime can run in a Vite environment, for example through a Vite plugin that your platform provides, you can render requests there instead, so that development behaves like production:

  • In the code that runs in that environment, import server from @sveltejs/kit/adapter/dev. It has the same API as the server that builder.generateServerInstance writes for production: call await server.init({ env }) and server.respond(request, { getClientAddress })
  • Add a dev.respond function to your adapter that sends each request to that code and returns its response. SvelteKit calls it after serving static files, imported assets and the service worker, and logs the response as usual

Edit this page on GitHub llms.txt

previous next