From 2ea1e883186660b48f0ea8c4da7fead5fb74e313 Mon Sep 17 00:00:00 2001 From: Hippo <6137925+hippotastic@users.noreply.github.com> Date: Tue, 30 Jan 2024 16:42:14 +0100 Subject: [PATCH] Add JS support to `@astrojs/starlight/expressive-code` export (#1440) --- .changeset/tidy-apes-camp.md | 5 ++ packages/starlight/expressive-code.d.ts | 35 ++++++++++ packages/starlight/expressive-code.mjs | 21 ++++++ .../integrations/expressive-code/exports.ts | 70 ------------------- .../integrations/expressive-code/index.ts | 3 +- packages/starlight/internal.ts | 5 ++ packages/starlight/package.json | 5 +- 7 files changed, 71 insertions(+), 73 deletions(-) create mode 100644 .changeset/tidy-apes-camp.md create mode 100644 packages/starlight/expressive-code.d.ts create mode 100644 packages/starlight/expressive-code.mjs delete mode 100644 packages/starlight/integrations/expressive-code/exports.ts diff --git a/.changeset/tidy-apes-camp.md b/.changeset/tidy-apes-camp.md new file mode 100644 index 00000000000..e6d74e0abac --- /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 00000000000..3e1c258a3bc --- /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 00000000000..0d91d786c5a --- /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 `` 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 3616c08d2df..00000000000 --- 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 1fe6fe87a7d..5d2af27dd03 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 d2d9f83d284..61583fc8cef 100644 --- a/packages/starlight/internal.ts +++ b/packages/starlight/internal.ts @@ -1 +1,6 @@ +/** + * @file This file contains utility functions imported by the `` 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 207835df068..76bc80f4f51 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"