From 5aadff938c26610e3f71be1c1774d0ba082c7dae Mon Sep 17 00:00:00 2001 From: Brad Adams Date: Wed, 12 Oct 2022 23:45:06 +0200 Subject: [PATCH 1/6] fix: broken TRANSLATING guide links (#1779) + Fix relative links to directories within the repo --- TRANSLATING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/TRANSLATING.md b/TRANSLATING.md index 6a1818bce78c1..49c947d8c45f9 100644 --- a/TRANSLATING.md +++ b/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 repo. 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`](../src/pages) directory of this repo. 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`](../src/i18n/de) for examples of these three files. ### How do I find the thing I want to translate? From fa96b4dd3496c434ccfd207de3afb65feb24d1f3 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 12 Oct 2022 19:35:59 -0300 Subject: [PATCH 2/6] remove problematic links --- TRANSLATING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/TRANSLATING.md b/TRANSLATING.md index 49c947d8c45f9..e805b0ecc5611 100644 --- a/TRANSLATING.md +++ b/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`](../src/pages) directory of this repo. 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 repo. 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`](../src/i18n/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? From bbb4f430a6fa2e26eb65db6a1ac99a154c6321d9 Mon Sep 17 00:00:00 2001 From: "Fred K. Bot" <108291165+fredkbot@users.noreply.github.com> Date: Thu, 13 Oct 2022 05:22:27 -0700 Subject: [PATCH 3/6] ci: update integration docs (#1787) Co-authored-by: delucis --- .../en/guides/integrations-guide/node.md | 76 +++++++++++-------- 1 file changed, 45 insertions(+), 31 deletions(-) diff --git a/src/pages/en/guides/integrations-guide/node.md b/src/pages/en/guides/integrations-guide/node.md index b325ecb65208c..dc80641c3fe5c 100644 --- a/src/pages/en/guides/integrations-guide/node.md +++ b/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 From d04cdd57ce92f35d85059caf5b07c801ce75f6fb Mon Sep 17 00:00:00 2001 From: "Fred K. Bot" <108291165+fredkbot@users.noreply.github.com> Date: Thu, 13 Oct 2022 09:44:27 -0700 Subject: [PATCH 4/6] ci: update reference docs (#1786) Co-authored-by: delucis Co-authored-by: Sarah Rainsberger --- .../en/reference/configuration-reference.md | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/src/pages/en/reference/configuration-reference.md b/src/pages/en/reference/configuration-reference.md index 16baf4d73c19d..bf9c78b655eff 100644 --- a/src/pages/en/reference/configuration-reference.md +++ b/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 + +

+ +**Type:** `string`
+**Default:** `'./dist/client'` +

+ +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 + +

+ +**Type:** `string`
+**Default:** `'./dist/server'` +

+ +Controls the output directory of server JavaScript when building to SSR. + +This value is relative to the `outDir`. + +```js +{ + build: { + server: './server' + } +} +``` + + +### build.serverEntry + +

+ +**Type:** `string`
+**Default:** `'entry.mjs'` +

+ +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`. From 82d2b61c99505021d77dba0c67d927a8106f62a7 Mon Sep 17 00:00:00 2001 From: Brad Adams Date: Thu, 13 Oct 2022 18:46:50 +0200 Subject: [PATCH 5/6] fix: missing package.json example comma (#1792) Co-authored-by: Sarah Rainsberger --- src/pages/en/guides/deploy/deno.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/en/guides/deploy/deno.md b/src/pages/en/guides/deploy/deno.md index b9af18827fa50..84974c307e3c1 100644 --- a/src/pages/en/guides/deploy/deno.md +++ b/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= --no-static --include=./dist ./dist/server/entry.mjs" } } From 2a5c454519bdd7905c5cb164fd5c53975e9ec9a0 Mon Sep 17 00:00:00 2001 From: Nate Moore Date: Thu, 13 Oct 2022 12:12:34 -0500 Subject: [PATCH 6/6] Update CLI Reference with `--site` & `--base` flags (#1646) Co-authored-by: Sarah Rainsberger --- src/pages/en/reference/cli-reference.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/pages/en/reference/cli-reference.md b/src/pages/en/reference/cli-reference.md index 02c200e39da92..3ca81a129bbba 100644 --- a/src/pages/en/reference/cli-reference.md +++ b/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` + + + +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.