From ab1010ec0a982d06f34b0d5fba2b7291df31acbf Mon Sep 17 00:00:00 2001 From: Luiz Ferraz Date: Thu, 5 Sep 2024 00:41:03 -0300 Subject: [PATCH 1/2] Update docs for advanced APIs --- .../docs/en/reference/cli-reference.mdx | 93 ++++++++++++++++--- 1 file changed, 82 insertions(+), 11 deletions(-) diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index afe217ebaa227..d480d1e07b95b 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -480,9 +480,9 @@ interface AstroInlineConfig extends AstroUserConfig { 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 (default) or unset, Astro will search for an `astro.config.(js,mjs,ts,mts)` 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. +If a relative path is set, it will resolve based on the `root` option. Set to `false` to disable loading any config files. @@ -516,7 +516,7 @@ The logging level to filter messages logged by Astro. ### `dev()` -**Type:** `(inlineConfig: AstroInlineConfig) => AstroDevServer` +**Type:** `(inlineConfig: AstroInlineConfig) => Promise` Similar to [`astro dev`](#astro-dev), it runs Astro's development server. @@ -531,9 +531,40 @@ const devServer = await dev({ await devServer.stop(); ``` +#### `DevServer` + +```ts +export interface DevServer { + address: AddressInfo; + handle: (req: http.IncomingMessage, res: http.ServerResponse) => void; + watcher: vite.FSWatcher; + stop(): Promise; +} +``` + +##### `address` + +The address the dev server is listening on. + +The semantics for this address are as defined by Node's [net.Server `address` method](https://nodejs.org/api/net.html#serveraddress). + +##### `handle` + +A handle for raw Node HTTP requests. It receives an [`http.IncomingMessage`](https://nodejs.org/api/http.html#class-httpincomingmessage) and an [`http.ServerResponse`](https://nodejs.org/api/http.html#class-httpserverresponse) in the same state as expected for a [listener to `request` events](https://nodejs.org/api/http.html#event-request). + +##### `watcher` + +The [Chokidar file watcher](https://github.com/paulmillr/chokidar#getting-started) as exposed by [Vite's development server](https://vitejs.dev/guide/api-javascript#vitedevserver). + +##### `stop` + +Stops the development server, closing all idle connection and stop listening to new connection. + +Returns a Promise that resolves once all pending requests have been fulfilled and all idle connections have been closed. + ### `build()` -**Type:** `(inlineConfig: AstroInlineConfig) => void` +**Type:** `(inlineConfig: AstroInlineConfig) => Promise` Similar to [`astro build`](#astro-build), it builds your site for deployment. @@ -547,9 +578,12 @@ await build({ ### `preview()` -**Type:** `(inlineConfig: AstroInlineConfig) => AstroPreviewServer` +**Type:** `(inlineConfig: AstroInlineConfig) => Promise` -Similar to [`astro preview`](#astro-preview), it starts a local server to serve your static `dist/` directory. +Similar to [`astro preview`](#astro-preview), it starts a local server to serve your build output. + +If no adapter is set in the configuration, the preview server will only serve the built static files. +If an adapter is set in the configuration, the preview server is provided by the adapter. Adapters are not required to provide a preview server, so this feature may not be available depending on your adapter of choice. ```js import { preview } from "astro"; @@ -562,20 +596,57 @@ const previewServer = await preview({ await previewServer.stop(); ``` +#### `PreviewServer` + +```ts +export interface PreviewServer { + host?: string; + port: number; + closed(): Promise; + stop(): Promise; +} +``` + +##### `host` + +The host where the server is listening on. + +Adapters are allowed to leave this field unset, the semantics of that are implementation-specific. + +##### `port` + +The port where the server is listening on. + +##### `closed` + +Returns a Promise that will resolve once the server is closed and reject if an error happens on the server. + +##### `stop` + +Signals the preview server to close, stop accepting requests and drop idle connections. + +The returned promise resolves when that signal is sent. + +:::caution +Contrary to the [`DevServer`](#devserver), awaiting the promise returned by this `stop()` method does not ensure that the server has completely closed. The adapter in use _may_ provide that guarantee, but it is not required. Instead the equivalent of calling `await devServer.stop()` is: +```ts +await previewServer.stop(); +await previewServer.closed(); +``` +::: + ### `sync()` -**Type:** `(inlineConfig: AstroInlineConfig) => number` +**Type:** `(inlineConfig: AstroInlineConfig) => Promise` -Similar to [`astro sync`](#astro-sync), it generates TypeScript types for all Astro modules +Similar to [`astro sync`](#astro-sync), it generates TypeScript types for all Astro modules. ```js import { sync } from "astro"; -const exitCode = await sync({ +await sync({ root: "./my-project", }); - -process.exit(exitCode) ``` ## Astro Studio CLI From b1d50283e28bfa73f65fa3df36f97867f2932f54 Mon Sep 17 00:00:00 2001 From: Luiz Ferraz Date: Thu, 5 Sep 2024 10:21:53 -0300 Subject: [PATCH 2/2] A lot of talking and a lot of doc'ing Co-authored-by: Chris Swithinbank --- .../docs/en/reference/cli-reference.mdx | 36 ++++++++----------- 1 file changed, 14 insertions(+), 22 deletions(-) diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index d480d1e07b95b..4db54aee5eb2e 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -546,21 +546,21 @@ export interface DevServer { The address the dev server is listening on. -The semantics for this address are as defined by Node's [net.Server `address` method](https://nodejs.org/api/net.html#serveraddress). +This property contains the value returned by Node's [`net.Server#address()` method](https://nodejs.org/api/net.html#serveraddress). -##### `handle` +##### `handle()` -A handle for raw Node HTTP requests. It receives an [`http.IncomingMessage`](https://nodejs.org/api/http.html#class-httpincomingmessage) and an [`http.ServerResponse`](https://nodejs.org/api/http.html#class-httpserverresponse) in the same state as expected for a [listener to `request` events](https://nodejs.org/api/http.html#event-request). +A handle for raw Node HTTP requests. You can call `handle()` with an [`http.IncomingMessage`](https://nodejs.org/api/http.html#class-httpincomingmessage) and an [`http.ServerResponse`](https://nodejs.org/api/http.html#class-httpserverresponse) instead of sending a request through the network. ##### `watcher` The [Chokidar file watcher](https://github.com/paulmillr/chokidar#getting-started) as exposed by [Vite's development server](https://vitejs.dev/guide/api-javascript#vitedevserver). -##### `stop` +##### `stop()` -Stops the development server, closing all idle connection and stop listening to new connection. +Stops the development server. This closes all idle connections and stops listening for new connections. -Returns a Promise that resolves once all pending requests have been fulfilled and all idle connections have been closed. +Returns a `Promise` that resolves once all pending requests have been fulfilled and all idle connections have been closed. ### `build()` @@ -609,31 +609,23 @@ export interface PreviewServer { ##### `host` -The host where the server is listening on. +The host where the server is listening for connections. -Adapters are allowed to leave this field unset, the semantics of that are implementation-specific. +Adapters are allowed to leave this field unset. The value of `host` is implementation-specific. ##### `port` -The port where the server is listening on. +The port where the server is listening for connections. -##### `closed` +##### `stop()` -Returns a Promise that will resolve once the server is closed and reject if an error happens on the server. +Asks the preview server to close, stop accepting requests, and drop idle connections. -##### `stop` +The returned `Promise` resolves when the close request has been sent. This does not mean that the server has closed yet. Use the [`closed()`](#closed) method if you need to ensure the server has fully closed. -Signals the preview server to close, stop accepting requests and drop idle connections. +##### `closed()` -The returned promise resolves when that signal is sent. - -:::caution -Contrary to the [`DevServer`](#devserver), awaiting the promise returned by this `stop()` method does not ensure that the server has completely closed. The adapter in use _may_ provide that guarantee, but it is not required. Instead the equivalent of calling `await devServer.stop()` is: -```ts -await previewServer.stop(); -await previewServer.closed(); -``` -::: +Returns a `Promise` that will resolve once the server is closed and reject if an error happens on the server. ### `sync()`