Deploy your site to a Node.js server
npm install astrojs-node-aws-amplifyastro add command. This will install the adapter and make the appropriate changes to your astro.config.mjs file in one step.
sh
Using NPM
npx astro add node
Using Yarn
yarn astro add node
Using PNPM
pnpm astro add node
`
$3
If you prefer to install the adapter manually instead, complete the following two steps:
1. Install the Node adapter to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal:
`bash
npm install @astrojs/node
`
1. Add two new lines to your astro.config.mjs project configuration file.
`diff lang="js"
// astro.config.mjs
import { defineConfig } from 'astro/config';
+ import node from '@astrojs/node';
export default defineConfig({
+ output: 'server',
+ adapter: node({
+ mode: 'standalone',
+ }),
});
`
Configuration
@astrojs/node can be configured by passing options into the adapter function. The following options are available:
$3
Controls whether the adapter builds to middleware or standalone mode.
- middleware mode allows the built output to be used as middleware for another Node.js server, like Express.js or Fastify.
`js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
export default defineConfig({
output: 'server',
adapter: node({
mode: 'middleware',
}),
});
`
- standalone mode builds to server that automatically starts with the entry module is run. This allows you to more easily deploy your build to a host without any additional code.
Usage
First, performing a build. Depending on which mode selected (see above) follow the appropriate steps below:
$3
The server entrypoint is built to ./dist/server/entry.mjs by default. This module exports a handler function that can be used with any framework that supports the Node request and response objects.
For example, with Express:
`js
// run-server.mjs
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';
const app = express();
// Change this based on your astro.config.mjs, base option.
// They should match. The default value is "/".
const base = '/';
app.use(base, express.static('dist/client/'));
app.use(ssrHandler);
app.listen(8080);
`
Or, with Fastify (>4):
`js
// run-server.mjs
import Fastify from 'fastify';
import fastifyMiddie from '@fastify/middie';
import fastifyStatic from '@fastify/static';
import { fileURLToPath } from 'node:url';
import { handler as ssrHandler } from './dist/server/entry.mjs';
const app = Fastify({ logger: true });
await app
.register(fastifyStatic, {
root: fileURLToPath(new URL('./dist/client', import.meta.url)),
})
.register(fastifyMiddie);
app.use(ssrHandler);
app.listen({ port: 8080 });
`
Additionally, you can also pass in an object to be accessed with Astro.locals or in Astro middleware:
`js
// run-server.mjs
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';
const app = express();
app.use(express.static('dist/client/'));
app.use((req, res, next) => {
const locals = {
title: 'New title',
};
ssrHandler(req, res, next, locals);
});
app.listen(8080);
`
Note that middleware mode does not do file serving. You'll need to configure your HTTP framework to do that for you. By default the client assets are written to ./dist/client/.
$3
In standalone mode a server starts when the server entrypoint is run. By default it is built to ./dist/server/entry.mjs. You can run it with:
`shell
node ./dist/server/entry.mjs
`
For standalone mode the server handles file servering in addition to the page and API routes.
#### Custom host and port
You can override the host and port the standalone server runs on by passing them as environment variables at runtime:
`shell
HOST=0.0.0.0 PORT=4321 node ./dist/server/entry.mjs
`
#### HTTPS
By default the standalone server uses HTTP. This works well if you have a proxy server in front of it that does HTTPS. If you need the standalone server to run HTTPS itself you need to provide your SSL key and certificate.
You can pass the path to your key and certification via the environment variables SERVER_CERT_PATH and SERVER_KEY_PATH. This is how you might pass them in bash:
`bash
SERVER_KEY_PATH=./private/key.pem SERVER_CERT_PATH=./private/cert.pem node ./dist/server/entry.mjs
`
#### Runtime environment variables
If an .env file containing environment variables is present when the build process is run, these values will be hard-coded in the output, just as when generating a static website.
During the build, the runtime variables must be absent from the .env file, and you must provide Astro with every environment variable to expect at run-time: VARIABLE_1=placeholder astro build. This signals to Astro that the actual value will be available when the built application is run. The placeholder value will be ignored by the build process, and Astro will use the value provided at run-time.
In the case of multiple run-time variables, store them in a seperate file (e.g. .env.runtime) from .env. Start the build with the following command:
`sh
export $(cat .env.runtime) && astro build
`
#### Assets
In standalone mode, assets in your dist/client/ folder are served via the standalone server. You might be deploying these assets to a CDN, in which case the server will never actually be serving them. But in some cases, such as intranet sites, it's fine to serve static assets directly from the application server.
Assets in the dist/client/_astro/ folder are the ones that Astro has built. These assets are all named with a hash and therefore can be given long cache headers. Internally the adapter adds this header for these assets:
`
Cache-Control: public, max-age=31536000, immutable
`
Troubleshooting
$3
You may see this when running the entry script if it was built with npm or Yarn. This is a known issue that may be fixed in a future release. As a workaround, add "path-to-regexp" to the noExternal array:
`diff lang="js"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
export default defineConfig({
output: 'server',
adapter: node(),
+ vite: {
+ ssr: {
+ noExternal: ['path-to-regexp'],
+ },
+ },
});
`
For more help, check out the #support` channel on Discord. Our friendly Support Squad members are here to help!