This adapter allows Astro to deploy your SSR site to Node targets.
Why @astrojs/nodeSection titled Why @astrojs/node
If you’re using Astro as a static site builder—its behavior out of the box—you don’t need an adapter.
If you wish to use server-side rendering (SSR), Astro requires an adapter that matches your deployment runtime.
InstallationSection titled Installation
Add the Node adapter to enable SSR in your Astro project with the following
astro add command. This will install the adapter and make the appropriate changes to your
astro.config.mjs file in one step.
If you prefer to install the adapter manually instead, complete the following two steps:
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:
Add two new lines to your
astro.config.mjsproject configuration file.
ConfigurationSection titled Configuration
@astrojs/node can be configured by passing options into the adapter function. The following options are available:
Controls whether the adapter builds to
middlewaremode allows the built output to be used as middleware for another Node.js server, like Express.js or Fastify.
standalonemode 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.
UsageSection titled Usage
First, performing a build. Depending on which
mode selected (see above) follow the appropriate steps below:
MiddlewareSection titled Middleware
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
For example, with Express:
Or, with Fastify (>4):
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
StandaloneSection titled Standalone
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:
For standalone mode the server handles file servering in addition to the page and API routes.
Custom host and portSection titled Custom host and port
You can override the host and port the standalone server runs on by passing them as environment variables at runtime:
HTTPSSection titled 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_KEY_PATH. This is how you might pass them in bash:
TroubleshootingSection titled Troubleshooting
SyntaxError: Named export ‘compile’ not foundSection titled SyntaxError: Named export ‘compile’ not found
You may see this when running the entry script if it was built with npm or Yarn. This is a known issue that will be fixed in a future release. As a workaround, add
"path-to-regexp" to the
For more help, check out the
#support channel on Discord. Our friendly Support Squad members are here to help!
You can also check our Astro Integration Documentation for more on integrations.
ContributingSection titled Contributing
This package is maintained by Astro’s Core team. You’re welcome to submit an issue or PR!
ChangelogSection titled Changelog
See CHANGELOG.md for a history of changes to this integration.