Export experimental JS API (#7979)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

Author: 3 people

.changeset/many-pears-explode.md

@@ -0,0 +1,35 @@
+---
+'astro': major
+---
+
+Export experimental `dev`, `build`, `preview`, and `sync` APIs from `astro`. These APIs allow you to run Astro's commands programmatically, and replaces the previous entry point that runs the Astro CLI.
+
+While these APIs are experimental, the inline config parameter is relatively stable without foreseeable changes. However, the returned results of these APIs are more likely to change in the future.
+
+```ts
+import { dev, build, preview, sync, type AstroInlineConfig } from 'astro';
+
+// Inline Astro config object.
+// Provide a path to a configuration file to load or set options directly inline.
+const inlineConfig: AstroInlineConfig = {
+  // Inline-specific options...
+  configFile: './astro.config.mjs',
+  logLevel: 'info',
+  // Standard Astro config options...
+  site: 'https://example.com',
+};
+
+// Start the Astro dev server
+const devServer = await dev(inlineConfig);
+await devServer.stop();
+
+// Build your Astro project
+await build(inlineConfig);
+
+// Preview your built project
+const previewServer = await preview(inlineConfig);
+await previewServer.stop();
+
+// Generate types for your Astro project
+await sync(inlineConfig);
+```

packages/astro/index.d.ts

@@ -0,0 +1,2 @@
+export type * from './dist/@types/astro.js';
+export * from './dist/core/index.js';

packages/astro/package.json

@@ -12,7 +12,7 @@
   },
   "bugs": "https://github.com/withastro/astro/issues",
   "homepage": "https://astro.build",
-  "types": "./dist/@types/astro.d.ts",
+  "types": "./index.d.ts",
   "typesVersions": {
     "*": {
       "app": [
@@ -31,8 +31,8 @@
   },
   "exports": {
     ".": {
-      "types": "./dist/@types/astro.d.ts",
-      "default": "./astro.js"
+      "types": "./index.d.ts",
+      "default": "./dist/core/index.js"
     },
     "./env": "./env.d.ts",
     "./types": "./types.d.ts",
@@ -90,6 +90,7 @@
     "tsconfigs",
     "dist",
     "astro.js",
+    "index.d.ts",
     "config.d.ts",
     "config.mjs",
     "zod.d.ts",

packages/astro/src/@types/astro.ts

@@ -143,7 +143,7 @@ export interface CLIFlags {
  */
 export interface AstroGlobal<
 	Props extends Record<string, any> = Record<string, any>,
-	Self = AstroComponentFactory
+	Self = AstroComponentFactory,
 > extends AstroGlobalPartial,
 		AstroSharedContext<Props> {
 	/**
@@ -1404,13 +1404,39 @@ export interface AstroConfig extends AstroConfigType {
 	// TypeScript still confirms zod validation matches this type.
 	integrations: AstroIntegration[];
 }
+/**
+ * An inline Astro config that takes highest priority when merging with the user config,
+ * and includes inline-specific options to configure how Astro runs.
+ */
 export interface AstroInlineConfig extends AstroUserConfig, AstroInlineOnlyConfig {}
 export interface AstroInlineOnlyConfig {
+	/**
+	 * 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.
+	 */
 	configFile?: string | false;
+	/**
+	 * The mode used when building your site to generate either "development" or "production" code.
+	 */
 	mode?: RuntimeMode;
+	/**
+	 * 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.
+	 *
+	 * @default "info"
+	 */
 	logLevel?: LoggerLevel;
 	/**
-	 * @internal for testing only
+	 * @internal for testing only, use `logLevel` instead.
 	 */
 	logging?: LogOptions;
 }

packages/astro/src/cli/build/index.ts

@@ -25,7 +25,5 @@ export async function build({ flags }: BuildOptions) {
 
 	const inlineConfig = flagsToAstroInlineConfig(flags);
 
-	await _build(inlineConfig, {
-		teardownCompiler: true,
-	});
+	await _build(inlineConfig);
 }

packages/astro/src/cli/check/index.ts

@@ -27,7 +27,7 @@ export async function check(flags: Arguments) {
 	// Run sync before check to make sure types are generated.
 	// NOTE: In the future, `@astrojs/check` can expose a `before lint` hook so that this works during `astro check --watch` too.
 	// For now, we run this once as usually `astro check --watch` is ran alongside `astro dev` which also calls `astro sync`.
-	const { sync } = await import('../../core/sync/index.js');
+	const { default: sync } = await import('../../core/sync/index.js');
 	const inlineConfig = flagsToAstroInlineConfig(flags);
 	const exitCode = await sync(inlineConfig);
 	if (exitCode !== 0) {

packages/astro/src/cli/sync/index.ts

@@ -1,6 +1,6 @@
 import type yargs from 'yargs-parser';
 import { printHelp } from '../../core/messages.js';
-import { sync as _sync } from '../../core/sync/index.js';
+import _sync from '../../core/sync/index.js';
 import { flagsToAstroInlineConfig } from '../flags.js';
 
 interface SyncOptions {

packages/astro/src/core/README.md

@@ -1,6 +1,8 @@
 # `core/`
 
-Code that executes within the top-level Node context. Contains the main Astro logic for the `build` and `dev` commands, and also manages the Vite server and SSR.
+Code that executes within the top-level Node context. Contains the main Astro logic for the `build`, `dev`, `preview`, and `sync` commands, and also manages the Vite server and SSR.
+
+The `core/index.ts` file is the main entry point for the `astro` package.
 
 [See CONTRIBUTING.md](../../../../CONTRIBUTING.md) for a code overview.
 

packages/astro/src/core/build/index.ts

@@ -37,14 +37,22 @@ export interface BuildOptions {
 	/**
 	 * Teardown the compiler WASM instance after build. This can improve performance when
 	 * building once, but may cause a performance hit if building multiple times in a row.
+	 *
+	 * @internal only used for testing
+	 * @default true
 	 */
 	teardownCompiler?: boolean;
 }
 
-/** `astro build` */
+/**
+ * Builds your site for deployment. By default, this will generate static files and place them in a dist/ directory.
+ * If SSR is enabled, this will generate the necessary server files to serve your site.
+ *
+ * @experimental The JavaScript API is experimental
+ */
 export default async function build(
 	inlineConfig: AstroInlineConfig,
-	options: BuildOptions
+	options?: BuildOptions
 ): Promise<void> {
 	applyPolyfill();
 	const logging = createNodeLogging(inlineConfig);
@@ -82,7 +90,7 @@ class AstroBuilder {
 		}
 		this.settings = settings;
 		this.logging = options.logging;
-		this.teardownCompiler = options.teardownCompiler ?? false;
+		this.teardownCompiler = options.teardownCompiler ?? true;
 		this.routeCache = new RouteCache(this.logging);
 		this.origin = settings.config.site
 			? new URL(settings.config.site).origin

packages/astro/src/core/dev/dev.ts

@@ -18,7 +18,12 @@ export interface DevServer {
 	stop(): Promise<void>;
 }
 
-/** `astro dev` */
+/**
+ * Runs Astro’s development server. This is a local HTTP server that doesn’t bundle assets.
+ * It uses Hot Module Replacement (HMR) to update your browser as you save changes in your editor.
+ *
+ * @experimental The JavaScript API is experimental
+ */
 export default async function dev(inlineConfig: AstroInlineConfig): Promise<DevServer> {
 	const devStart = performance.now();
 	await telemetry.record([]);