@sveltejs/adapter-node

What is @sveltejs/adapter-node?

@sveltejs/adapter-node is an adapter for SvelteKit that allows you to build and deploy your SvelteKit application as a Node.js server. This adapter is useful for deploying SvelteKit applications to environments where Node.js is available, such as traditional hosting providers or custom server setups.

What are @sveltejs/adapter-node's main functionalities?

Basic Setup

This code demonstrates how to configure the @sveltejs/adapter-node in your SvelteKit project. The `adapter` function is imported and used in the `kit` configuration. You can specify the output directory, whether to precompress files, and environment variables for the host and port.

```javascript
// svelte.config.js
import adapter from '@sveltejs/adapter-node';

export default {
  kit: {
    adapter: adapter({
      out: 'build',
      precompress: false,
      env: {
        host: 'HOST',
        port: 'PORT'
      }
    })
  }
};
```

Custom Server

This code demonstrates how to create a custom server using Express.js with the built SvelteKit application. The `handler` from the build directory is used to handle requests, and the server listens on a specified port.

```javascript
// server.js
import { handler } from './build/handler.js';
import express from 'express';

const app = express();

app.use(handler);

const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});
```

Environment Variables

This code demonstrates how to use environment variables with @sveltejs/adapter-node. The `env` option in the adapter configuration allows you to specify environment variables for the host and port. These variables can be defined in a `.env` file.

```javascript
// svelte.config.js
import adapter from '@sveltejs/adapter-node';

export default {
  kit: {
    adapter: adapter({
      env: {
        host: 'HOST',
        port: 'PORT'
      }
    })
  }
};

// .env
HOST=localhost
PORT=3000
```

Other packages similar to @sveltejs/adapter-node

@sveltejs/adapter-static

@sveltejs/adapter-static is an adapter for SvelteKit that allows you to build your application as a set of static files. This is useful for deploying to static hosting providers like GitHub Pages or Netlify. Unlike @sveltejs/adapter-node, it does not require a Node.js server.

@sveltejs/adapter-vercel

@sveltejs/adapter-vercel is an adapter for SvelteKit that allows you to deploy your application to Vercel. It is specifically designed to work with Vercel's serverless functions and deployment platform. This adapter abstracts away the server setup, unlike @sveltejs/adapter-node, which requires a custom server.

@sveltejs/adapter-netlify

@sveltejs/adapter-netlify is an adapter for SvelteKit that allows you to deploy your application to Netlify. It is designed to work with Netlify's serverless functions and deployment platform. Similar to @sveltejs/adapter-vercel, it abstracts away the server setup.

README

@sveltejs/adapter-node

Adapter for SvelteKit apps that generates a standalone Node server.

Usage

Install with npm i -D @sveltejs/adapter-node, then add the adapter to your svelte.config.js:

// svelte.config.js
import adapter from '@sveltejs/adapter-node';

export default {
  kit: {
    adapter: adapter()
  }
};

Deploying

You will need the output directory (build by default), the project's package.json, and the production dependencies in node_modules to run the application. Production dependencies can be generated with npm ci --prod (you can skip this step if your app doesn't have any dependencies). You can then start your app with

node build

Development dependencies will be bundled into your app using rollup. To control whether a given package is bundled or externalised, place it in devDependencies or dependencies respectively in your package.json.

Environment variables

In dev and preview, SvelteKit will read environent variables from your .env file (or .env.local, or .env.[mode], as determined by Vite.)

In production, .env files are not automatically loaded. To do so, install dotenv in your project...

npm install dotenv

...and invoke it before running the built app:

-node build
+node -r dotenv/config build

PORT and HOST

By default, the server will accept connections on 0.0.0.0 using port 3000. These can be customised with the PORT and HOST environment variables:

HOST=127.0.0.1 PORT=4000 node build

ORIGIN, PROTOCOL_HEADER and HOST_HEADER

HTTP doesn't give SvelteKit a reliable way to know the URL that is currently being requested. The simplest way to tell SvelteKit where the app is being served is to set the ORIGIN environment variable:

ORIGIN=https://my.site node build

With this, a request for the /stuff pathname will correctly resolve to https://my.site/stuff. Alternatively, you can specify headers that tell SvelteKit about the request protocol and host, from which it can construct the origin URL:

PROTOCOL_HEADER=x-forwarded-proto HOST_HEADER=x-forwarded-host node build

x-forwarded-proto and x-forwarded-host are de facto standard headers that forward the original protocol and host if you're using a reverse proxy (think load balancers and CDNs). You should only set these variables if your server is behind a trusted reverse proxy; otherwise, it'd be possible for clients to spoof these headers.

If adapter-node can't correctly determine the URL of your deployment, you may experience this error when using form actions:

Cross-site POST form submissions are forbidden

ADDRESS_HEADER and XFF_DEPTH

The RequestEvent object passed to hooks and endpoints includes an event.getClientAddress() function that returns the client's IP address. By default this is the connecting remoteAddress. If your server is behind one or more proxies (such as a load balancer), this value will contain the innermost proxy's IP address rather than the client's, so we need to specify an ADDRESS_HEADER to read the address from:

ADDRESS_HEADER=True-Client-IP node build

Headers can easily be spoofed. As with PROTOCOL_HEADER and HOST_HEADER, you should know what you're doing before setting these.

If the ADDRESS_HEADER is X-Forwarded-For, the header value will contain a comma-separated list of IP addresses. The XFF_DEPTH environment variable should specify how many trusted proxies sit in front of your server. E.g. if there are three trusted proxies, proxy 3 will forward the addresses of the original connection and the first two proxies:

<client address>, <proxy 1 address>, <proxy 2 address>

Some guides will tell you to read the left-most address, but this leaves you vulnerable to spoofing:

<spoofed address>, <client address>, <proxy 1 address>, <proxy 2 address>

Instead, we read from the right, accounting for the number of trusted proxies. In this case, we would use XFF_DEPTH=3.

If you need to read the left-most address instead (and don't care about spoofing) — for example, to offer a geolocation service, where it's more important for the IP address to be real than trusted, you can do so by inspecting the x-forwarded-for header within your app.

BODY_SIZE_LIMIT

The maximum request body size to accept in bytes including while streaming. Defaults to 512kb. You can disable this option with a value of 0 and implement a custom check in handle if you need something more advanced.

Options

The adapter can be configured with various options:

// svelte.config.js
import adapter from '@sveltejs/adapter-node';

export default {
  kit: {
    adapter: adapter({
      // default options are shown
      out: 'build',
      precompress: false,
      envPrefix: ''
    })
  }
};

out

The directory to build the server to. It defaults to build — i.e. node build would start the server locally after it has been created.

precompress

Enables precompressing using gzip and brotli for assets and prerendered pages. It defaults to false.

envPrefix

If you need to change the name of the environment variables used to configure the deployment (for example, to deconflict with environment variables you don't control), you can specify a prefix:

envPrefix: 'MY_CUSTOM_';

MY_CUSTOM_HOST=127.0.0.1 \
MY_CUSTOM_PORT=4000 \
MY_CUSTOM_ORIGIN=https://my.site \
node build

Custom server

The adapter creates two files in your build directory — index.js and handler.js. Running index.js — e.g. node build, if you use the default build directory — will start a server on the configured port.

Alternatively, you can import the handler.js file, which exports a handler suitable for use with Express, Connect or Polka (or even just the built-in http.createServer) and set up your own server:

// my-server.js
import { handler } from './build/handler.js';
import express from 'express';

const app = express();

// add a route that lives separately from the SvelteKit app
app.get('/healthcheck', (req, res) => {
  res.end('ok');
});

// let SvelteKit handle everything else, including serving prerendered pages and static assets
app.use(handler);

app.listen(3000, () => {
  console.log('listening on port 3000');
});

Troubleshooting

Is there a hook for cleaning up before the server exits?

There's nothing built-in to SvelteKit for this, because such a cleanup hook depends highly on the execution environment you're on. For Node, you can use its built-in process.on(..) to implement a callback that runs before the server exits:

function shutdownGracefully() {
  // anything you need to clean up manually goes in here
  db.shutdown();
}

process.on('SIGINT', shutdownGracefully);
process.on('SIGTERM', shutdownGracefully);

Changelog

The Changelog for this package is available on GitHub.

License

MIT