import type { ConfigEnv } from "vite"; import type { ApiCustomElementDeclaration, ApiJson } from "@arcgis/api-extractor/apiJson"; import type { LuminaOptions, AssetSpec, AssetTransformer } from "../options.js"; import type { ContextDirectories } from "./types.js"; import type { ApiExtractor } from "@arcgis/api-extractor/extractor/ApiExtractor"; /** A compiler state and context object that is shared across plugins. */ export abstract class CompilerContext { /** * Core paths selected while exposing ESM modules from Vite's development server. * * @internal */ _localCdnCore?: { readonly packageLocation: string; readonly sourceLocation?: string; }; apiExtractor?: ApiExtractor; /** * The api.json stores information about the structure of all components in * the package (their properties, methods, events, JSDoc and etc). * * You can augment the api.json generation using the `apiJson` option in * `useLumina()` */ apiJson: ApiJson; /** A flattened api.json listing all components in this package. */ apiJsonComponents: ApiCustomElementDeclaration[]; /** In some test environments, api.json will never be produced. */ apiJsonEnabled: boolean; /** List of directories of common interest to the compiler */ dir: ContextDirectories; /** * The environment that Vite is running in * * By default, `npx vite` will run in `development` mode. and `npx vite build` * will run in `production` mode. However, you can do a development-mode build * using `npx vite build --mode development` * * - By default, source maps are generated only in development builds. * - Minification happens in production builds. */ environment: "development" | "production"; /** Whether HMR is enabled during the current Vite run */ hmrEnabled: boolean; /** * Whether to extract full API information, with type-checking. This is the * case during build or when running under Storybook. Otherwise, the dev * server keeps API extraction to bare minimum to reduce needless overhead. * Only the information necessary for the dev server to lazy load is * extracted. */ isFullApiExtraction: boolean; /** True in `vite build --watch` mode. */ isInBuildWatch: boolean; /** * It is a best practice to keep local build behavior as similar as possible * to CI build. Thus, only use this option if some behavior really * needs to be different in the CI. * * For example, `@arcgis/lumina-compiler` will by default automatically update * your package's package.json if it is missing some properties. However, this * behavior is disabled on the CI machine. * * @default Boolean(process.env.CI) */ readonly isInCi: boolean; /** * If running inside of Vitest as part of Puppeteer test integration * * @deprecated * For new projects, use Vitest browser mode instead of Puppeteer. * See documentation: https://webgis.esri.com/references/lumina/testing */ isInPuppeteerTestBackEnd: boolean; /** If running in a Vite instance created by Vitest Puppeteer integration. */ isInPuppeteerTestFrontEnd: boolean; /** Whether Vite build/serve is running inside of Storybook. */ isInStorybook: boolean; /** * It is a best practice to keep production behavior as similar as possible * to test environment. Thus, only use this option if some behavior really * needs to be different in test environment. * * For example, `@arcgis/lumina-compiler` will by default automatically update * your package's package.json if it is missing some properties. However, this * behavior is disabled in test environment. * * Test environment is detected in the following cases: * - Running in test mode (`npx vite build --mode test`). In such case * CompilerContext.environment will still be set to `development` * - Running in vitest - a test runner for Vite (`npx vitest`) * - Running vitest performance benchmark (`npx vitest benchmark`) */ isInTest: boolean; /** Options passed to `useLumina()` */ readonly options: LuminaOptions; /** * Like this.apiJson, but also contains members decorated with the `@private` * JSDoc tag. */ privateApiJson: ApiJson; /** * Whether minification is enabled for transformed JSX (lit-html templates) * and generated component code. * * @internal */ shouldMinify: boolean; /** * Like this.shouldMinify, but true when in test mode. Reasons: * - If accessing .textContent, the whitespace amount differs between minified * and non-minified lit-html templates. In Stencil's JSX this was not the * case. To ease migration of tests, we minify lit-html in tests too. * - From the above, you can see that minification does change semantics in * some cases. To have tests be truer to the real world, we minify in tests. * * Also, true during build as per * https://devtopia.esri.com/WebGIS/webgis-sdk/issues/2084 * * @internal */ shouldMinifyJsx: boolean; /** * Vite can be run in two modes: * - Serve the project (with watching for changes and hot module reloading). * This is the case when you run Vite as `npx vite` * - Build the project (with bundling and optimizations). * This is the case when you run Vite as `npx vite build` * * `@arcgis/lumina-compiler` does not know what environment Vite is running * in until the `apply()` Vite plugin hook is called by Vite. That means, you * should not try to read this property before the `apply()` hook is called. */ viteCommand: ConfigEnv["command"]; /** * A utility for making Vite copy assets to the output folder during build or * making Vite serve them when running in serve mode * * @param assets * @param transformers * @param apply * @example * ```ts * // vite.config.ts * import { defineConfig } from "vite"; * import { useLumina } from "@arcgis/lumina-compiler"; * * export default defineConfig((env) => { * const lumina = useLumina(); * * lumina.context.provideAssets([ * { * type: "dynamic", * source: () => new Date().toString(), * destination: "build_date.txt", * }, * ]); * * return { * plugins: [lumina], * }; * }); * ``` */ provideAssets(assets: AssetSpec[], transformers?: AssetTransformer[], apply?: CompilerContext["viteCommand"]): void; }