Docs for writing an adapter API

sveltejs · Jul 7, 2021 · 31a2625 · 31a2625
1 parent 71480bb
commit 31a2625
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 2 deletions.
diff --git a/documentation/docs/10-adapters.md b/documentation/docs/10-adapters.md
@@ -38,9 +38,9 @@ A variety of official adapters exist for serverless platforms...
 - [`adapter-netlify`](https://github.com/sveltejs/kit/tree/master/packages/adapter-netlify) — for [Netlify](https://netlify.com)
 - [`adapter-vercel`](https://github.com/sveltejs/kit/tree/master/packages/adapter-vercel) — for [Vercel](https://vercel.com)
 
-...and others:
+...and traditional platforms:
 
 - [`adapter-node`](https://github.com/sveltejs/kit/tree/master/packages/adapter-node) — for creating self-contained Node apps
 - [`adapter-static`](https://github.com/sveltejs/kit/tree/master/packages/adapter-static) — for prerendering your entire site as a collection of static files
 
-> The adapter API is still in flux and will likely change before 1.0.
+You may also [write your own](#writing-an-adapter).
diff --git a/documentation/docs/80-adapter-api.md b/documentation/docs/80-adapter-api.md
@@ -0,0 +1,29 @@
+---
+title: Writing an Adapter
+---
+
+We recommend [looking at the source for an adapter](https://github.com/sveltejs/kit/tree/master/packages) to a platform similar to yours and copying it as a starting point.
+
+Adapters must implement the following API:
+```
+export default function () {
+	/** @type {import('@sveltejs/kit').Adapter} */
+	return {
+		name: '',
+		async adapt({ utils, config }) {
+		}
+	};
+}
+```
+
+Within the `adapt` method, there are a number of things that an adapter should do:
+- Clear out the build directory
+- Provide code that:
+  - Calls `init`
+  - Converts from the patform's request to a SvelteKit request, call `render`, convert from a SveteKit reponse to the platform's
+- Bundle the output to avoid needing to install dependencies on the target platform, etc. if desired
+- Globally shim `fetch` to work on the target platform. SvelteKit provides a `@sveltejs/kit/install-fetch` helper to use `node-fetch`
+- Call `prerender`
+- Put the user's static files and the generated JS/CSS in the correct location for the target platform
+
+> The adapter API may change before 1.0.