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}`}'`;
});
}