From 39a3e9764a462d81e887ca1a2cb7d850a6bae862 Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 16 Aug 2023 18:14:12 +0800 Subject: [PATCH 1/4] Document experimental JS API --- .../docs/en/reference/cli-reference.mdx | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index 79f29ba0c085c..bbc0ab461d965 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -373,3 +373,85 @@ Automatically opens the app in the browser on server start. ### `--help` Prints the help message and exits. + +## Advanced APIs (Experimental) + +If you need more control when running Astro, the `"astro"` package also exports APIs to programmatically run the CLI commands. These APIs are experimental and their API signature may change in any version. + +### `AstroInlineConfig` + +The `AstroInlineConfig` type is used by all of the command APIs below. It extends from the user [Astro config](../configuration-reference) type: + +```ts +interface AstroInlineConfig extends AstroUserConfig { + configFile?: string | false; + mode?: "development" | "production"; + logLevel?: "debug" | "info" | "warn" | "error" | "silent"; +} +``` + +#### `configFile` + +

+ +**Type:** `string | false`
+**Default:** `undefined` +

+ +A custom path to the Astro config file. If relative, it'll resolve based on the current working directory. +Set to `false` to disable loading any config files. + +If this value is undefined or unset, Astro will search for an `astro.config.(js,mjs,ts)` file relative to +the `root` and load the config file if found. + +The inline config passed in this object will take highest priority when merging with the loaded user config. + +#### `mode` + +

+ +**Type:** `"development" | "production"`
+**Default:** `"development"` when running `astro dev`, `"production"` when running `astro build` +

+ +The mode used when building your site to generate either "development" or "production" code. + +#### `logLevel` + +

+ +**Type:** `"debug" | "info" | "warn" | "error" | "silent"`
+**Default:** `"info"` +

+ +The logging level to filter messages logged by Astro. + +- `"debug"`: Log everything, including noisy debugging diagnostics. +- `"info"`: Log informational messages, warnings, and errors. +- `"warn"`: Log warnings and errors. +- `"error"`: Log errors only. +- `"silent"`: No logging. + +### `dev()` + +**Type:** `(inlineConfig: AstroInlineConfig) => AstroDevServer` + +Similar to [`astro dev`](#astro-dev), it runs Astro's development server. + +### `build()` + +**Type:** `(inlineConfig: AstroInlineConfig) => void` + +Similar to [`astro build`](#astro-build), it builds your site for deployment. + +### `preview()` + +**Type:** `(inlineConfig: AstroInlineConfig) => AstroPreviewServer` + +Similar to [`astro preview`](#astro-preview), it starts a local server to serve your static `dist/` directory. + +### `sync()` + +**Type:** `(inlineConfig: AstroInlineConfig) => number` + +Similar to [`astro sync`](#astro-sync), it generates TypeScript types for all Astro modules From 5e6c8d3943a2c05536339b20fba228ee7343c756 Mon Sep 17 00:00:00 2001 From: bluwy Date: Wed, 16 Aug 2023 18:21:27 +0800 Subject: [PATCH 2/4] Add code examples --- .../docs/en/reference/cli-reference.mdx | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index bbc0ab461d965..02e617018c868 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -438,20 +438,60 @@ The logging level to filter messages logged by Astro. Similar to [`astro dev`](#astro-dev), it runs Astro's development server. +```js +import { dev } from "astro"; + +const devServer = await dev({ + root: "./my-project", +}); + +// Stop the server if needed +await devServer.stop(); +``` + ### `build()` **Type:** `(inlineConfig: AstroInlineConfig) => void` Similar to [`astro build`](#astro-build), it builds your site for deployment. +```js +import { build } from "astro"; + +await build({ + root: "./my-project", +}); +``` + ### `preview()` **Type:** `(inlineConfig: AstroInlineConfig) => AstroPreviewServer` Similar to [`astro preview`](#astro-preview), it starts a local server to serve your static `dist/` directory. +```js +import { preview } from "astro"; + +const previewServer = await preview({ + root: "./my-project", +}); + +// Stop the server if needed +await previewServer.stop(); +``` + ### `sync()` **Type:** `(inlineConfig: AstroInlineConfig) => number` Similar to [`astro sync`](#astro-sync), it generates TypeScript types for all Astro modules + +```js +import { sync } from "astro"; + +const exitCode = await sync({ + root: "./my-project", +}); + +process.exit(exitCode) +``` From 81aca17d6a5e7b977448935b0d12654aff07de15 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 16 Aug 2023 09:59:37 -0300 Subject: [PATCH 3/4] fix link format --- src/content/docs/en/reference/cli-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index 02e617018c868..723fea016be7c 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -380,7 +380,7 @@ If you need more control when running Astro, the `"astro"` package also exports ### `AstroInlineConfig` -The `AstroInlineConfig` type is used by all of the command APIs below. It extends from the user [Astro config](../configuration-reference) type: +The `AstroInlineConfig` type is used by all of the command APIs below. It extends from the user [Astro config](/en/reference/configuration-reference/) type: ```ts interface AstroInlineConfig extends AstroUserConfig { From 530d3fc61164d31de7db531a548d9471cf2b8d99 Mon Sep 17 00:00:00 2001 From: Bjorn Lu Date: Mon, 21 Aug 2023 13:43:46 +0800 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Sarah Rainsberger --- src/content/docs/en/reference/cli-reference.mdx | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index 723fea016be7c..8ec7b2ccc255c 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -376,7 +376,9 @@ Prints the help message and exits. ## Advanced APIs (Experimental) -If you need more control when running Astro, the `"astro"` package also exports APIs to programmatically run the CLI commands. These APIs are experimental and their API signature may change in any version. +If you need more control when running Astro, the `"astro"` package also exports APIs to programmatically run the CLI commands. + +These APIs are experimental and their API signature may change. Any updates will be mentioned in the [Astro changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) and the information below will always show the current, up-to-date information. ### `AstroInlineConfig` @@ -398,11 +400,13 @@ interface AstroInlineConfig extends AstroUserConfig { **Default:** `undefined`

-A custom path to the Astro config file. If relative, it'll resolve based on the current working directory. -Set to `false` to disable loading any config files. +A custom path to the Astro config file. + +If this value is undefined (default) or unset, Astro will search for an `astro.config.(js,mjs,ts)` file relative to the `root` and load the config file if found. -If this value is undefined or unset, Astro will search for an `astro.config.(js,mjs,ts)` file relative to -the `root` and load the config file if found. +If a relative path is set, it will resolve based on the current working directory. + +Set to `false` to disable loading any config files. The inline config passed in this object will take highest priority when merging with the loaded user config.