import { Extractor, ExtractorConfig } from '@microsoft/api-extractor'; import { existsSync, readFileSync, writeFileSync } from 'node:fs'; import { dirname, join, relative } from 'node:path'; import ts from 'typescript'; import { generateQwikApiMarkdownDocs, generateQwikRouterApiMarkdownDocs } from './api-docs.ts'; import { type BuildConfig, copyFile, ensureDir, panic } from './util.ts'; // jsx-runtime just re-exports JSX, so skip api-extractor. export function writeJsxRuntimeDts(config: BuildConfig) { const jsxContent = readFileSync(join(config.srcQwikDir, 'jsx-runtime.ts'), 'utf-8'); writeFileSync( join(config.distQwikPkgDir, 'jsx-runtime.d.ts'), `// re-export to make TS happy when not using nodenext import resolution\n${jsxContent}` ); ensureDir(join(config.distQwikPkgDir, 'jsx-runtime')); writeFileSync( join(config.distQwikPkgDir, 'jsx-runtime', 'index.d.ts'), `// re-export to make TS happy when not using nodenext import resolution\nexport * from '../jsx-runtime.js';` ); } /** * Create each submodule's bundled dts file, and ensure the public API has not changed for a * production build. */ export async function apiExtractorQwik(config: BuildConfig) { // core // Run the api extractor for each of the submodules createTypesApi(config, join(config.srcQwikDir, 'core'), join(config.distQwikPkgDir, 'core.d.ts')); // Special case for jsx-runtime: // It only re-exports JSX. Don't duplicate the types writeJsxRuntimeDts(config); createTypesApi(config, config.qwikVitePkgDir, join(config.distQwikPkgDir, 'optimizer.d.ts')); createTypesApi( config, join(config.srcQwikDir, 'server'), join(config.distQwikPkgDir, 'server.d.ts') ); createTypesApi( config, join(config.srcQwikDir, 'serializer'), join(config.distQwikPkgDir, 'serializer.d.ts') ); createTypesApi( config, join(config.srcQwikDir, 'testing'), join(config.distQwikPkgDir, 'testing', 'index.d.ts') ); createTypesApi( config, join(config.srcQwikDir, 'build'), join(config.distQwikPkgDir, 'build', 'index.d.ts') ); createTypesApi( config, join(config.srcQwikDir, 'web-worker'), join(config.distQwikPkgDir, 'worker', 'index.d.mts') ); createTypesApi( config, join(config.srcQwikDir, 'insights'), join(config.distQwikPkgDir, 'insights', 'index.d.ts') ); createTypesApi( config, join(config.srcQwikDir, 'insights', 'vite'), join(config.distQwikPkgDir, 'insights', 'vite', 'index.d.ts') ); generateServerReferenceModules(config); validateQwikTypesWithNode16(config); const apiJsonInputDir = join(config.rootDir, 'dist-dev', 'api'); await generateQwikApiMarkdownDocs(config, apiJsonInputDir); console.log('🥶', 'qwik d.ts API files generated'); } export async function apiExtractorOptimizer(config: BuildConfig) { createTypesApi( config, config.optimizerPkgDir, join(config.optimizerPkgDir, 'dist', 'index.d.ts') ); console.log('🥶', 'optimizer d.ts API files generated'); } export async function apiExtractorQwikRouter(config: BuildConfig) { // qwik-router createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'runtime', 'src'), join(config.packagesDir, 'qwik-router', 'lib', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'runtime', 'src', 'service-worker'), join(config.packagesDir, 'qwik-router', 'lib', 'service-worker.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'buildtime', 'vite'), join(config.packagesDir, 'qwik-router', 'lib', 'vite', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'adapters', 'azure-swa', 'vite'), join(config.packagesDir, 'qwik-router', 'lib', 'adapters', 'azure-swa', 'vite', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'adapters', 'cloudflare-pages', 'vite'), join( config.packagesDir, 'qwik-router', 'lib', 'adapters', 'cloudflare-pages', 'vite', 'index.d.ts' ) ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'adapters', 'cloud-run', 'vite'), join(config.packagesDir, 'qwik-router', 'lib', 'adapters', 'cloud-run', 'vite', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'adapters', 'deno-server', 'vite'), join(config.packagesDir, 'qwik-router', 'lib', 'adapters', 'deno-server', 'vite', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'adapters', 'bun-server', 'vite'), join(config.packagesDir, 'qwik-router', 'lib', 'adapters', 'bun-server', 'vite', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'adapters', 'node-server', 'vite'), join(config.packagesDir, 'qwik-router', 'lib', 'adapters', 'node-server', 'vite', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'adapters', 'netlify-edge', 'vite'), join(config.packagesDir, 'qwik-router', 'lib', 'adapters', 'netlify-edge', 'vite', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'adapters', 'shared', 'vite'), join(config.packagesDir, 'qwik-router', 'lib', 'adapters', 'shared', 'vite', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'adapters', 'ssg', 'vite'), join(config.packagesDir, 'qwik-router', 'lib', 'adapters', 'ssg', 'vite', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'adapters', 'vercel-edge', 'vite'), join(config.packagesDir, 'qwik-router', 'lib', 'adapters', 'vercel-edge', 'vite', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'middleware', 'azure-swa'), join(config.packagesDir, 'qwik-router', 'lib', 'middleware', 'azure-swa', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'middleware', 'aws-lambda'), join(config.packagesDir, 'qwik-router', 'lib', 'middleware', 'aws-lambda', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'middleware', 'cloudflare-pages'), join(config.packagesDir, 'qwik-router', 'lib', 'middleware', 'cloudflare-pages', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'middleware', 'bun'), join(config.packagesDir, 'qwik-router', 'lib', 'middleware', 'bun', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'middleware', 'deno'), join(config.packagesDir, 'qwik-router', 'lib', 'middleware', 'deno', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'middleware', 'netlify-edge'), join(config.packagesDir, 'qwik-router', 'lib', 'middleware', 'netlify-edge', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'middleware', 'node'), join(config.packagesDir, 'qwik-router', 'lib', 'middleware', 'node', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'middleware', 'request-handler'), join(config.packagesDir, 'qwik-router', 'lib', 'middleware', 'request-handler', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'middleware', 'firebase'), join(config.packagesDir, 'qwik-router', 'lib', 'middleware', 'firebase', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'ssg'), join(config.packagesDir, 'qwik-router', 'lib', 'ssg', 'index.d.ts') ); createTypesApi( config, join(config.packagesDir, 'qwik-router', 'src', 'middleware', 'vercel-edge'), join(config.packagesDir, 'qwik-router', 'lib', 'middleware', 'vercel-edge', 'index.d.ts') ); generateQwikRouterReferenceModules(config); const apiJsonInputDir = join(config.rootDir, 'dist-dev', 'api'); await generateQwikRouterApiMarkdownDocs(config, apiJsonInputDir); console.log('🥶', 'qwik-router d.ts API files generated'); } /** * Without this, a CI-only API change reports just "API changed true" and the report it wants lives * in a build dir nobody can read from the log. */ function printApiReportDiff(committedPath: string, generatedPath: string) { const read = (path: string) => { try { return readFileSync(path, 'utf-8').split('\n'); } catch { return null; } }; const committed = read(committedPath); const generated = read(generatedPath); if (!committed || !generated) { console.error(`Could not read both reports to diff:\n ${committedPath}\n ${generatedPath}`); return; } console.error(`--- committed: ${committedPath}`); console.error(`+++ generated: ${generatedPath}`); for (let i = 0; i < Math.max(committed.length, generated.length); i++) { if (committed[i] !== generated[i]) { if (committed[i] !== undefined) { console.error(`-${i + 1}: ${committed[i]}`); } if (generated[i] !== undefined) { console.error(`+${i + 1}: ${generated[i]}`); } } } } function createTypesApi(config: BuildConfig, inPath: string, outPath: string) { const extractorConfigPath = join(inPath, 'api-extractor.json'); const extractorConfig = ExtractorConfig.loadFileAndPrepare(extractorConfigPath); const result = Extractor.invoke(extractorConfig, { localBuild: !!config.dev, showVerboseMessages: true, showDiagnostics: true, messageCallback(msg) { msg.handled = true; if (msg.logLevel === 'verbose') { return; } if (msg.text.includes('Analysis will use')) { return; } if (msg.messageId === 'console-api-report-copied') { if (config.dev) { return; } console.error( `❌ API Extractor, submodule: "${inPath}"\n${extractorConfigPath} has API changes.\n` ); return; } if ( msg.messageId === 'console-compiler-version-notice' || msg.messageId === 'ae-undocumented' ) { return; } console.error(`❌ API Extractor, submodule: "${inPath}"\n${extractorConfigPath}\n`, msg); }, }); if (!result.succeeded) { console.log( 'API build results: API changed', result.apiReportChanged, 'errors', result.errorCount, 'warnings', result.warningCount ); if (result.apiReportChanged) { printApiReportDiff( result.extractorConfig.reportFilePath, result.extractorConfig.reportTempFilePath ); } panic( `Use "pnpm api.update" to automatically update the .md files if the api changes were expected` ); } for (const path of [ result.extractorConfig.betaTrimmedFilePath, result.extractorConfig.untrimmedFilePath, ]) { if (path) { const fixed = fixDtsContent(config, path, result.extractorConfig.mainEntryPointFilePath); writeFileSync(path, fixed); } } } export function generateQwikRouterReferenceModules(config: BuildConfig) { const srcModulesPath = join(config.packagesDir, 'qwik-router', 'lib'); const destModulesPath = join(srcModulesPath, 'modules.d.ts'); copyFile(join(config.packagesDir, 'qwik-router', 'modules.d.ts'), destModulesPath); // manually prepend the ts reference since api extractor removes it const prependReferenceDts = `/// \n\n`; const distIndexPath = join(srcModulesPath, 'index.d.ts'); let serverDts = readFileSync(distIndexPath, 'utf-8'); serverDts = prependReferenceDts + serverDts; writeFileSync(distIndexPath, serverDts); } export function generateServerReferenceModules(config: BuildConfig) { // server-modules.d.ts const referenceDts = `/// declare module '@qwik-client-manifest' { /** @deprecated Use \`getClientManifest()\` instead */ const manifest: import('./optimizer.js').QwikManifest; export { manifest }; } // MD declare module '*.md' { const node: import('./core-internal.js').FunctionComponent; export const frontmatter: Record; export default node; } // MDX declare module '*.mdx' { const node: import('./core-internal.js').FunctionComponent; export const frontmatter: Record; export default node; } // SVG ?jsx declare module '*.svg?jsx' { const Cmp: import('./core-internal.js').FunctionComponent export default Cmp; } // Image ?jsx declare module '*?jsx' { const Cmp: import('./core-internal.js').FunctionComponent> export default Cmp; export const width: number; export const height: number; export const srcSet: string; } // Image &jsx declare module '*&jsx' { const Cmp: import('./core-internal.js').FunctionComponent> export default Cmp; export const width: number; export const height: number; export const srcSet: string; } `; const destServerModulesPath = join(config.distQwikPkgDir, 'server-modules.d.ts'); writeFileSync(destServerModulesPath, referenceDts); // manually prepend the ts reference since api extractor removes it const prependReferenceDts = `/// \n\n`; const distServerPath = join(config.distQwikPkgDir, 'server.d.ts'); let serverDts = readFileSync(distServerPath, 'utf-8'); serverDts = prependReferenceDts + serverDts; writeFileSync(distServerPath, serverDts); } /** * Fix up the generated dts content so that its imports also resolve with `moduleResolution: * node16`, which requires explicit file extensions. */ function fixDtsContent(config: BuildConfig, dtsPath: string, entryDtsPath: string) { let dts = readFileSync(dtsPath, 'utf-8'); dts = addRelativeImportExtensions(dts, dirname(entryDtsPath)); const isQwikCoreDts = !relative(join(config.packagesDir, 'qwik'), dtsPath).startsWith('..'); if (isQwikCoreDts) { dts = relativizeQwikCoreImports(config, dts, dirname(dtsPath)); } // replace QWIK_VERSION with the actual version number, useful for debugging return dts.replace(/QWIK_VERSION/g, config.distVersion); } function readQwikPackageExports(config: BuildConfig) { const qwikPkgDir = join(config.packagesDir, 'qwik'); const pkg = JSON.parse(readFileSync(join(qwikPkgDir, 'package.json'), 'utf-8')); return { qwikPkgDir, exports: pkg.exports as Record }; } /** Node16 resolution is the strictest: it requires explicit extensions and honors `exports`. */ function validateQwikTypesWithNode16(config: BuildConfig) { const { qwikPkgDir, exports } = readQwikPackageExports(config); const typesFiles = Object.values(exports) .map((entry) => entry.types) .filter((types): types is string => types !== undefined) .map((types) => join(qwikPkgDir, types)); const program = ts.createProgram(typesFiles, { module: ts.ModuleKind.Node16, moduleResolution: ts.ModuleResolutionKind.Node16, noEmit: true, strict: true, skipLibCheck: false, types: [], }); const diagnostics = ts.getPreEmitDiagnostics(program); if (diagnostics.length > 0) { panic( `@qwik.dev/core types fail with moduleResolution node16:\n${ts.formatDiagnostics( diagnostics, { getCurrentDirectory: () => qwikPkgDir, getNewLine: () => '\n', getCanonicalFileName: (fileName) => fileName, } )}` ); } } const importSpecifierRegex = /(^(?:import|export)\b[^\n]*?\bfrom |^\}\s*from |\bimport\()'([^']+)'/gm; /** The rollups mirror the source layout, so resolve their relative imports vs the entry dts. */ function addRelativeImportExtensions(dts: string, entryDtsDir: string) { return dts.replace(importSpecifierRegex, (match, prefix: string, specifier: string) => { if (!specifier.startsWith('.')) { return match; } const target = join(entryDtsDir, specifier); if (existsSync(`${target}.d.ts`)) { return `${prefix}'${specifier}.js'`; } if (existsSync(join(target, 'index.d.ts'))) { return `${prefix}'${specifier}/index.js'`; } return match; }); } /** Point `@qwik.dev/core` self-imports at the dts files of this package, not a node_modules copy. */ function relativizeQwikCoreImports(config: BuildConfig, dts: string, dtsDir: string) { const { qwikPkgDir, exports } = readQwikPackageExports(config); return dts.replace(importSpecifierRegex, (match, prefix: string, specifier: string) => { const selfImport = /^@qwik\.dev\/core(\/.*)?$/.exec(specifier); if (!selfImport) { return match; } const subpath = selfImport[1]; // The public root types are a subset, internal dts files need all of them const exportKey = subpath ? `.${subpath}` : './internal'; const typesPath = exports[exportKey]?.types; if (!typesPath) { throw new Error(`No types export for "${specifier}" in ${qwikPkgDir}/package.json`); } const jsPath = relative(dtsDir, join(qwikPkgDir, typesPath)) .replaceAll('\\', '/') .replace(/\.d\.(m?)ts$/, '.$1js'); return `${prefix}'${jsPath.startsWith('.') ? jsPath : `./${jsPath}`}'`; }); }