1 files changed, 46 insertions, 35 deletions
diff --git a/packages/integrations/node/README.md b/packages/integrations/node/README.md
index 7c95dd0ea..9e0f8150e 100644
--- a/packages/integrations/node/README.md
+++ b/packages/integrations/node/README.md
@@ -1,23 +1,23 @@
-# @astrojs/node 🔲
+# @astrojs/node
 
 This adapter allows Astro to deploy your SSR site to Node targets.
 
 - <strong>[Why Astro Node](#why-astro-node)</strong>
 - <strong>[Installation](#installation)</strong>
-- <strong>[Usage](#usage)</strong>
 - <strong>[Configuration](#configuration)</strong>
+- <strong>[Usage](#usage)</strong>
 - <strong>[Troubleshooting](#troubleshooting)</strong>
 - <strong>[Contributing](#contributing)</strong>
 - <strong>[Changelog](#changelog)</strong> 
 
 
-## Why Astro Node
+## 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)](https://docs.astro.build/en/guides/server-side-rendering/), Astro requires an adapter that matches your deployment runtime.
 
-[Node](https://nodejs.org/en/) is a JavaScript runtime for server-side code. Frameworks like [Express](https://expressjs.com/) are built on top of it and make it easier to write server applications in Node. This adapter provides access to Node's API and creates a script to run your Astro project that can be utilized in Node applications.
+[Node.js](https://nodejs.org/en/) is a JavaScript runtime for server-side code. @astrojs/node can be used either in standalone mode or as middleware for other http servers, such as [Express](https://expressjs.com/).
 
 ## Installation
 
@@ -42,23 +42,47 @@ If you prefer to install the adapter manually instead, complete the following tw
 
 1. Add two new lines to your `astro.config.mjs` project configuration file.
 
-    ```js title="astro.config.mjs" ins={2, 5-6}
+    ```js title="astro.config.mjs" ins={2, 5-8}
     import { defineConfig } from 'astro/config';
     import node from '@astrojs/node';
 
     export default defineConfig({
       output: 'server',
-      adapter: node(),
+      adapter: node({
+        mode: 'standalone'
+      }),
     });
     ```
 
+## Configuration
+
+@astrojs/node can be configured by passing options into the adapter function. The following options are available:
+
+### Mode
+
+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
+    import { defineConfig } from 'astro/config';
+    import nodejs 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
 
-After [performing a build](https://docs.astro.build/en/guides/deploy/#building-your-site-locally) there will be a `dist/server/entry.mjs` module that exposes a `handler` function. This works like a [middleware](https://expressjs.com/en/guide/using-middleware.html) function: it can handle incoming requests and respond accordingly. 
+First, [performing a build](https://docs.astro.build/en/guides/deploy/#building-your-site-locally). Depending on which `mode` selected (see above) follow the appropriate steps below:
 
+### Middleware
 
-### Using a middleware framework
-You can use this `handler` with any framework that supports the Node `request` and `response` objects.
+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:
 
@@ -73,40 +97,27 @@ app.use(ssrHandler);
 app.listen(8080);
 ```
 
+Note that middleware mode does not do file servering. You'll need to configure your HTTP framework to do that for you. By default the client assets are written to `./dist/client/`.
 
-### Using `http`
-
-This output script does not require you use Express and can work with even the built-in `http` and `https` node modules. The handler does follow the convention calling an error function when either
+### Standalone
 
-- A route is not found for the request.
-- There was an error rendering.
+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:
 
-You can use these to implement your own 404 behavior like so:
-
-```js
-import http from 'http';
-import { handler as ssrHandler } from './dist/server/entry.mjs';
-
-http.createServer(function(req, res) {
-  ssrHandler(req, res, err => {
-    if(err) {
-      res.writeHead(500);
-      res.end(err.toString());
-    } else {
-      // Serve your static assets here maybe?
-      // 404?
-      res.writeHead(404);
-      res.end();
-    }
-  });
-}).listen(8080);
+```shell
+node ./dist/server/entry.mjs
 ```
 
+For standalone mode the server handles file servering in addition to the page and API routes.
 
+#### HTTPS
 
-## Configuration
+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.
 
-This adapter does not expose any configuration options.
+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
+```
 
 ## Troubleshooting