Add JS support to @astrojs/starlight/expressive-code export (#1440)

.changeset/tidy-apes-camp.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Adds JS support to the `@astrojs/starlight/expressive-code` export to allow importing from non-TS environments.

packages/starlight/expressive-code.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @file This file provides the types for Starlight's `@astrojs/starlight/expressive-code` export.
+ */
+
+export * from 'astro-expressive-code';
+
+import type { StarlightExpressiveCodeOptions } from './integrations/expressive-code';
+
+export type { StarlightExpressiveCodeOptions };
+
+/**
+ * A utility function that helps you define an Expressive Code configuration object. It is meant
+ * to be used inside the optional config file `ec.config.mjs` located in the root directory
+ * of your Starlight project, and its return value to be exported as the default export.
+ *
+ * Expressive Code will automatically detect this file and use the exported configuration object
+ * to override its own default settings.
+ *
+ * Using this function is recommended, but not required. It just passes through the given object,
+ * but it also provides type information for your editor's auto-completion and type checking.
+ *
+ * @example
+ * ```js
+ * // ec.config.mjs
+ * import { defineEcConfig } from '@astrojs/starlight/expressive-code'
+ *
+ * export default defineEcConfig({
+ *   themes: ['starlight-dark', 'github-light'],
+ *   styleOverrides: {
+ *     borderRadius: '0.5rem',
+ *   },
+ * })
+ * ```
+ */
+export function defineEcConfig(config: StarlightExpressiveCodeOptions): StarlightExpressiveCodeOptions;

packages/starlight/expressive-code.mjs

@@ -0,0 +1,21 @@
+/**
+ * @file This file is exported by Starlight as `@astrojs/starlight/expressive-code`.
+ *
+ * It is required by the `<Code>` component to access the same configuration preprocessor
+ * function as the one used by the integration.
+ *
+ * It also provides access to all of the Expressive Code classes and functions without having
+ * to install `astro-expressive-code` as an additional dependency into a user's project
+ * (and thereby risiking version conflicts).
+ *
+ * Note: This file is intentionally not a TypeScript module to allow access to all exported
+ * functionality even if TypeScript is not available, e.g. from the `ec.config.mjs` file
+ * that does not get processed by Vite.
+ */
+
+export * from 'astro-expressive-code';
+
+// @ts-ignore - Types are provided by the separate `expressive-code.d.ts` file
+export function defineEcConfig(config) {
+	return config;
+}

packages/starlight/integrations/expressive-code/index.ts

@@ -179,8 +179,7 @@ export const starlightExpressiveCode = ({
 				}),
 				preprocessComponentConfig: `
 					import starlightConfig from 'virtual:starlight/user-config'
-					import { useTranslations } from '@astrojs/starlight/internal'
-					import { getStarlightEcConfigPreprocessor } from '@astrojs/starlight/expressive-code'
+					import { useTranslations, getStarlightEcConfigPreprocessor } from '@astrojs/starlight/internal'
 
 					export default getStarlightEcConfigPreprocessor({ starlightConfig, useTranslations })
 				`,

packages/starlight/internal.ts

@@ -1 +1,6 @@
+/**
+ * @file This file contains utility functions imported by the `<Code>` component.
+ */
+
 export { useTranslations } from './utils/translations';
+export { getStarlightEcConfigPreprocessor } from './integrations/expressive-code';

packages/starlight/package.json

@@ -158,7 +158,10 @@
     "./props": "./props.ts",
     "./schema": "./schema.ts",
     "./types": "./types.ts",
-    "./expressive-code": "./integrations/expressive-code/exports.ts",
+    "./expressive-code": {
+      "types": "./expressive-code.d.ts",
+      "default": "./expressive-code.mjs"
+    },
     "./index.astro": "./index.astro",
     "./404.astro": "./404.astro",
     "./style/markdown.css": "./style/markdown.css"