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

7 files changed, 71 insertions, 73 deletions

diff --git a/.changeset/tidy-apes-camp.md b/.changeset/tidy-apes-camp.md
new file mode 100644
index 00000000..e6d74e0a
--- /dev/null
+++ b/.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.
diff --git a/packages/starlight/expressive-code.d.ts b/packages/starlight/expressive-code.d.ts
new file mode 100644
index 00000000..3e1c258a
--- /dev/null
+++ b/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;
diff --git a/packages/starlight/expressive-code.mjs b/packages/starlight/expressive-code.mjs
new file mode 100644
index 00000000..0d91d786
--- /dev/null
+++ b/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;
+}
diff --git a/packages/starlight/integrations/expressive-code/exports.ts b/packages/starlight/integrations/expressive-code/exports.ts
deleted file mode 100644
index 3616c08d..00000000
--- a/packages/starlight/integrations/expressive-code/exports.ts
+++ /dev/null
@@ -1,70 +0,0 @@
-/**
- * @file This file is exported by Starlight as `@astrojs/starlight/expressive-code`
- * and can be used in your site's configuration to customize Expressive Code.
- *
- * It provides access to all of the Expressive Code classes and functions without having
- * to install `astro-expressive-code` as an additional dependency into your project
- * (and thereby risiking version conflicts).
- *
- * For example, you can use this to load custom themes from a JSONC file (JSON with comments)
- * that would otherwise be difficult to import, and pass them to the `themes` option:
- *
- * @example
- * ```js
- * // astro.config.mjs
- * import fs from 'node:fs';
- * import { defineConfig } from 'astro/config';
- * import starlight from '@astrojs/starlight';
- * import { ExpressiveCodeTheme } from '@astrojs/starlight/expressive-code';
- *
- * const jsoncString = fs.readFileSync(new URL(`./my-theme.jsonc`, import.meta.url), 'utf-8');
- * const myTheme = ExpressiveCodeTheme.fromJSONString(jsoncString);
- *
- * export default defineConfig({
- *   integrations: [
- *     starlight({
- *       title: 'My Starlight site',
- *       expressiveCode: {
- *         themes: [myTheme],
- *       },
- *     }),
- *   ],
- * });
- * ```
- */
-
-export * from 'astro-expressive-code';
-
-import type { StarlightExpressiveCodeOptions } from './index';
-
-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) {
-	return config;
-}
-
-export { getStarlightEcConfigPreprocessor } from './index';
diff --git a/packages/starlight/integrations/expressive-code/index.ts b/packages/starlight/integrations/expressive-code/index.ts
index 1fe6fe87..5d2af27d 100644
--- a/packages/starlight/integrations/expressive-code/index.ts
+++ b/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 })
 				`,
diff --git a/packages/starlight/internal.ts b/packages/starlight/internal.ts
index d2d9f83d..61583fc8 100644
--- a/packages/starlight/internal.ts
+++ b/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';
diff --git a/packages/starlight/package.json b/packages/starlight/package.json
index 207835df..76bc80f4 100644
--- a/packages/starlight/package.json
+++ b/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"