Merge branch 'main' into endpoint-context-api

TRANSLATING.md

@@ -66,7 +66,7 @@ Each of these content types lives in a different place.
 
 ### 1. Documentation pages
 
-Each documentation page lives in the [`src/pages`](../pages) directory of this <abbr title="repository">repo</abbr>. There you’ll find directories for all of the languages currently translated. Each page is a Markdown file to support rich text formatting. For example, the English language “Getting Started” page is at `src/pages/en/getting-started.md` and the same page in French is at `src/pages/fr/getting-started.md`.
+Each documentation page lives in the `src/pages` directory of this <abbr title="repository">repo</abbr>. There you’ll find directories for all of the languages currently translated. Each page is a Markdown file to support rich text formatting. For example, the English language “Getting Started” page is at `src/pages/en/getting-started.md` and the same page in French is at `src/pages/fr/getting-started.md`.
 
 ### 2. UI text
 
@@ -78,7 +78,7 @@ UI text lives in `src/i18n` with a folder for each language similar to how pages
 - `ui.ts` — translates miscellaneous bits of text found around the docs
 - `docsearch.ts` — translates the search component
 
-See [`src/i18n/de`](de) for examples of these three files.
+See `src/i18n/de` for examples of these three files.
 
 ### How do I find the thing I want to translate?
 

src/pages/en/guides/deploy/deno.md

@@ -157,7 +157,7 @@ If your project is stored on GitHub, the [Deno Deploy website](https://dash.deno
         "dev": "astro dev",
         "start": "astro dev",
         "build": "astro build",
-        "preview": "deno run --allow-net --allow-read --allow-env ./dist/server/entry.mjs"
+        "preview": "deno run --allow-net --allow-read --allow-env ./dist/server/entry.mjs",
         "deno-deploy": "npm run build && deployctl deploy --project=<MY-DENO-PROJECT> --no-static --include=./dist ./dist/server/entry.mjs"
       }
     }

src/pages/en/guides/integrations-guide/node.md

@@ -22,13 +22,13 @@ setup: |
 
 This adapter allows Astro to deploy your SSR site to Node targets.
 
-## 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)](/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
 
@@ -53,23 +53,47 @@ If you prefer to install the adapter manually instead, complete the following tw
 
 2.  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](/en/guides/deploy/) 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](/en/guides/deploy/). Depending on which `mode` selected (see above) follow the appropriate steps below:
 
-### Using a middleware framework
+### Middleware
 
-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:
 
@@ -84,37 +108,27 @@ app.use(ssrHandler);
 app.listen(8080);
 ```
 
-### Using `http`
+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/`.
 
-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:
+```shell
+node ./dist/server/entry.mjs
+```
 
-```js
-import http from 'http';
-import { handler as ssrHandler } from './dist/server/entry.mjs';
+For standalone mode the server handles file servering in addition to the page and API routes.
 
-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);
-```
+#### 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
 

src/pages/en/reference/cli-reference.md

@@ -3,6 +3,7 @@ layout: ~/layouts/MainLayout.astro
 title: CLI Reference
 i18nReady: true
 setup: |
+    import Since from '~/components/Since.astro';
     import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
 ---
 
@@ -167,6 +168,16 @@ Specifies the path to the config file relative to the project root. Defaults to
 astro --config config/astro.config.mjs dev
 ```
 
+### `--site`
+
+Configures the [`site`](/en/reference/configuration-reference/#site) for your project. Passing this flag will override the `site` value in your `astro.config.mjs` file, if one exists.
+
+### `--base`
+
+<Since v="1.4.1" />
+
+Configures the [`base`](/en/reference/configuration-reference/#base) for your project. Passing this flag will override the `base` value in your `astro.config.mjs` file, if one exists.
+
 ### `--verbose`
 
 Enables verbose logging, which is helpful when debugging an issue.

src/pages/en/reference/configuration-reference.md

@@ -107,6 +107,8 @@ The value can be either an absolute file system path or a path relative to the p
   outDir: './my-custom-build-directory'
 }
 ```
+**See Also:**
+- build.server
 
 
 ### site
@@ -245,6 +247,74 @@ Setting `build.format` controls what `Astro.url` is set to during the build. Whe
 This means that when you create relative URLs using `new URL('./relative', Astro.url)`, you will get consistent behavior between dev and build.
 
 
+### build.client
+
+<p>
+
+**Type:** `string`<br>
+**Default:** `'./dist/client'`
+</p>
+
+Controls the output directory of your client-side CSS and JavaScript when `output: 'server'` only.
+`outDir` controls where the code is built to.
+
+This value is relative to the `outDir`.
+
+```js
+{
+  output: 'server',
+  build: {
+    client: './client'
+  }
+}
+```
+
+
+### build.server
+
+<p>
+
+**Type:** `string`<br>
+**Default:** `'./dist/server'`
+</p>
+
+Controls the output directory of server JavaScript when building to SSR.
+
+This value is relative to the `outDir`.
+
+```js
+{
+  build: {
+    server: './server'
+  }
+}
+```
+
+
+### build.serverEntry
+
+<p>
+
+**Type:** `string`<br>
+**Default:** `'entry.mjs'`
+</p>
+
+Specifies the file name of the server entrypoint when building to SSR.
+This entrypoint is usually dependent on which host you are deploying to and
+will be set by your adapter for you.
+
+Note that it is recommended that this file ends with `.mjs` so that the runtime
+detects that the file is a JavaScript module.
+
+```js
+{
+  build: {
+    serverEntry: 'main.mjs'
+  }
+}
+```
+
+
 ## Server Options
 
 Customize the Astro dev server, used by both `astro dev` and `astro preview`.