diff --git a/.changeset/many-masks-smoke.md b/.changeset/many-masks-smoke.md new file mode 100644 index 0000000000..6d249eeb15 --- /dev/null +++ b/.changeset/many-masks-smoke.md @@ -0,0 +1,6 @@ +--- +'@backstage/repo-tools': minor +'@backstage/cli': minor +--- + +Remove support for the deprecated `--experimental-type-build` option for `package build`. diff --git a/REVIEWING.md b/REVIEWING.md index 43085090a8..7ed3fcda57 100644 --- a/REVIEWING.md +++ b/REVIEWING.md @@ -172,13 +172,7 @@ We generate API Reports using the [API Extractor](https://api-extractor.com/) to Each API report contains a list of all the exported types of each package. As long as the API report does not have any warnings it will contain the full publicly facing API of the package, meaning you do not need to consider any other changes to the package from the point of view of TypeScript API stability. -Exported types can be marked with either `@public`, `@alpha` or `@beta` release tags. It is only the `@public` exports that we consider to be part of the stable API. The `@alpha` and `@beta` exports are considered unstable and can be changed at any time without needing a breaking package versions bump. However, this **ONLY** applies if the package has been configured to use experimental type builds, which looks like this in `package.json`: - -```json - "build": "backstage-cli package build --experimental-type-build" -``` - -If a package does not have this configuration, then all exported types are considered stable, even if they are marked as `@alpha` or `@beta`. +Exported types can be marked with either `@public`, `@alpha` or `@beta` release tags. It is only the `@public` exports that we consider to be part of the stable API. The `@alpha` and `@beta` exports are considered unstable and can be changed at any time without needing a breaking package versions bump. #### Changes that are Not Considered Breaking diff --git a/docs/local-dev/cli-build-system.md b/docs/local-dev/cli-build-system.md index 61e24863fe..7bb4918d47 100644 --- a/docs/local-dev/cli-build-system.md +++ b/docs/local-dev/cli-build-system.md @@ -674,38 +674,3 @@ To add subpath exports to an existing package, simply add the desired `"exports" ```bash yarn backstage-cli migrate package-exports ``` - -## Experimental Type Build - -> Note: Experimental type builds are deprecated and will be removed in the future. They have been replaced by [subpath exports](#subpath-exports). - -The Backstage CLI has an experimental feature where multiple different type definition files can be generated for different release stages. The release stages are marked in the [TSDoc](https://tsdoc.org/) for each individual export, using either `@public`, `@alpha`, or `@beta`. Rather than just building a single `index.d.ts` file, the build process will instead output `index.d.ts`, `index.beta.d.ts`, and `index.alpha.d.ts`. Each of these files will have exports from more unstable release stages stripped, meaning that `index.d.ts` will omit all exports marked with `@alpha` or `@beta`, while `index.beta.d.ts` will omit all exports marked with `@alpha`. - -This feature is aimed at projects that publish to package registries and wish to maintain different levels of API stability within each package. There is no need to use this within a single monorepo, as it has no effect due to only applying to built and published packages. - -In order for the experimental type build to work, `@microsoft/api-extractor` must be installed in your project, as it is an optional peer dependency of the Backstage CLI. There are then three steps that need to be taken for each package where you want to enable this feature: - -- Add the `--experimental-type-build` flag to the `"build"` script of the package. -- Add either one or both of `"alphaTypes"` and `"betaTypes"` to the `"publishConfig"` of the package: - ```json - "publishConfig": { - ... - "types": "dist/index.d.ts", - "alphaTypes": "dist/index.alpha.d.ts", - "betaTypes": "dist/index.beta.d.ts" - }, - ``` -- Add either one or both of `"alpha"` and `"beta"` to the `"files"` of the package: - ```json - "files": [ - "dist", - "alpha", - "beta" - ] - ``` - -Once this setup is complete, users of the published packages will only be able to access the stable API via the main package entry point, for example `@acme/my-plugin`. Exports marked with `@alpha` or `@beta` will only be available via the `/alpha` entry point, for example `@acme/my-plugin/alpha`, and exports marked with `@beta` will only be available via `/beta`. This does not apply within the monorepo that contains the package. There all exports still have to be imported via the main entry point. - -Note that these different entry points are only separated during type checking. At runtime they all share the same code which contains the exports from all releases stages. - -An example of this setup can be seen in the [`@backstage/catalog-model`](https://github.com/backstage/backstage/blob/da0675bf9f28ed1460f03635a22d3c26abd14707/packages/catalog-model/package.json#L14) package, which has enabled `alpha` type exports. With this setup, exports marked as `@alpha` are only available for import via `@backstage/catalog-model/alpha`. The `@backstage/catalog-model` package currently does not have any exports marked as `@beta`, or a `/beta` entry point. diff --git a/packages/cli/cli-report.md b/packages/cli/cli-report.md index 9d6ffd3f69..9292f2ea37 100644 --- a/packages/cli/cli-report.md +++ b/packages/cli/cli-report.md @@ -224,7 +224,6 @@ Usage: backstage-cli package build [options] Options: --role --minify - --experimental-type-build --skip-build-dependencies --stats --config diff --git a/packages/cli/package.json b/packages/cli/package.json index 4f08231f7e..5fb892952f 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -175,16 +175,12 @@ "type-fest": "^2.19.0" }, "peerDependencies": { - "@microsoft/api-extractor": "^7.21.2", "@vitejs/plugin-react": "^4.0.4", "vite": "^4.4.9", "vite-plugin-html": "^3.2.0", "vite-plugin-node-polyfills": "^0.14.1" }, "peerDependenciesMeta": { - "@microsoft/api-extractor": { - "optional": true - }, "@vitejs/plugin-react": { "optional": true }, diff --git a/packages/cli/src/commands/build/command.ts b/packages/cli/src/commands/build/command.ts index 507085e0a0..1b3aeff2f9 100644 --- a/packages/cli/src/commands/build/command.ts +++ b/packages/cli/src/commands/build/command.ts @@ -65,6 +65,5 @@ export async function command(opts: OptionValues): Promise { return buildPackage({ outputs, minify: Boolean(opts.minify), - useApiExtractor: Boolean(opts.experimentalTypeBuild), }); } diff --git a/packages/cli/src/commands/index.ts b/packages/cli/src/commands/index.ts index ce4a4d2bae..fb0a55f37e 100644 --- a/packages/cli/src/commands/index.ts +++ b/packages/cli/src/commands/index.ts @@ -130,10 +130,6 @@ export function registerScriptCommand(program: Command) { '--minify', 'Minify the generated code. Does not apply to app or backend packages.', ) - .option( - '--experimental-type-build', - 'Enable experimental type build. Does not apply to app or backend packages. [DEPRECATED]', - ) .option( '--skip-build-dependencies', 'Skip the automatic building of local dependencies. Applies to backend packages only.', diff --git a/packages/cli/src/commands/migrate/packageScripts.ts b/packages/cli/src/commands/migrate/packageScripts.ts index 1552208a5f..e9ff20aed3 100644 --- a/packages/cli/src/commands/migrate/packageScripts.ts +++ b/packages/cli/src/commands/migrate/packageScripts.ts @@ -49,9 +49,6 @@ export async function command() { if (scripts.build?.includes('--minify')) { buildCmd.push('--minify'); } - if (scripts.build?.includes('--experimental-type-build')) { - buildCmd.push('--experimental-type-build'); - } if (scripts.build?.includes('--config')) { buildCmd.push(...(scripts.build.match(configArgPattern) ?? [])); } diff --git a/packages/cli/src/commands/repo/build.ts b/packages/cli/src/commands/repo/build.ts index 71e58c6201..32f227c208 100644 --- a/packages/cli/src/commands/repo/build.ts +++ b/packages/cli/src/commands/repo/build.ts @@ -137,7 +137,6 @@ export async function command(opts: OptionValues, cmd: Command): Promise { outputs, logPrefix: `${chalk.cyan(relativePath(paths.targetRoot, pkg.dir))}: `, minify: buildOptions.minify, - useApiExtractor: buildOptions.experimentalTypeBuild, }; }); diff --git a/packages/cli/src/lib/builder/buildTypeDefinitions.ts b/packages/cli/src/lib/builder/buildTypeDefinitions.ts deleted file mode 100644 index 3bf3a4495f..0000000000 --- a/packages/cli/src/lib/builder/buildTypeDefinitions.ts +++ /dev/null @@ -1,129 +0,0 @@ -/* - * Copyright 2020 The Backstage Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -import fs from 'fs-extra'; -import chalk from 'chalk'; -import { relative as relativePath, resolve as resolvePath } from 'path'; -import { paths } from '../paths'; -import { buildTypeDefinitionsWorker } from './buildTypeDefinitionsWorker'; -import { runWorkerThreads } from '../parallel'; - -// These message types are ignored since we want to avoid duplicating the logic of -// handling them correctly, and we already have the API Reports warning about them. -const ignoredMessages = new Set(['tsdoc-undefined-tag', 'ae-forgotten-export']); - -export async function buildTypeDefinitions( - targetDirs: string[] = [paths.targetDir], -) { - const packageDirs = targetDirs.map(dir => - relativePath(paths.targetRoot, dir), - ); - const entryPoints = await Promise.all( - packageDirs.map(async dir => { - const entryPoint = paths.resolveTargetRoot( - 'dist-types', - dir, - 'src/index.d.ts', - ); - - const declarationsExist = await fs.pathExists(entryPoint); - if (!declarationsExist) { - throw new Error( - `No declaration files found at ${entryPoint}, be sure to run ${chalk.bgRed.white( - 'yarn tsc', - )} to generate .d.ts files before packaging`, - ); - } - return entryPoint; - }), - ); - - const workerConfigs = packageDirs.map(packageDir => { - const targetDir = paths.resolveTargetRoot(packageDir); - const targetTypesDir = paths.resolveTargetRoot('dist-types', packageDir); - const extractorOptions = { - configObject: { - mainEntryPointFilePath: resolvePath(targetTypesDir, 'src/index.d.ts'), - bundledPackages: [], - - compiler: { - skipLibCheck: true, - tsconfigFilePath: paths.resolveTargetRoot('tsconfig.json'), - }, - - dtsRollup: { - enabled: true, - untrimmedFilePath: resolvePath(targetDir, 'dist/index.alpha.d.ts'), - betaTrimmedFilePath: resolvePath(targetDir, 'dist/index.beta.d.ts'), - publicTrimmedFilePath: resolvePath(targetDir, 'dist/index.d.ts'), - }, - - newlineKind: 'lf', - - projectFolder: targetDir, - }, - configObjectFullPath: targetDir, - packageJsonFullPath: resolvePath(targetDir, 'package.json'), - }; - return { extractorOptions, targetTypesDir }; - }); - - const typescriptDir = paths.resolveTargetRoot('node_modules/typescript'); - const hasTypescript = await fs.pathExists(typescriptDir); - const typescriptCompilerFolder = hasTypescript ? typescriptDir : undefined; - await runWorkerThreads({ - threadCount: 1, - workerData: { - entryPoints, - workerConfigs, - typescriptCompilerFolder, - }, - worker: buildTypeDefinitionsWorker, - onMessage: ({ - message, - targetTypesDir, - }: { - message: any; - targetTypesDir: string; - }) => { - if (ignoredMessages.has(message.messageId)) { - return; - } - - let text = `${message.text} (${message.messageId})`; - if (message.sourceFilePath) { - text += ' at '; - text += relativePath(targetTypesDir, message.sourceFilePath); - if (message.sourceFileLine) { - text += `:${message.sourceFileLine}`; - if (message.sourceFileColumn) { - text += `:${message.sourceFileColumn}`; - } - } - } - if (message.logLevel === 'error') { - console.error(chalk.red(`Error: ${text}`)); - } else if ( - message.logLevel === 'warning' || - message.category === 'Extractor' - ) { - console.warn(`Warning: ${text}`); - } else { - console.log(text); - } - }, - }); -} diff --git a/packages/cli/src/lib/builder/buildTypeDefinitionsWorker.ts b/packages/cli/src/lib/builder/buildTypeDefinitionsWorker.ts deleted file mode 100644 index c3c37d91cf..0000000000 --- a/packages/cli/src/lib/builder/buildTypeDefinitionsWorker.ts +++ /dev/null @@ -1,97 +0,0 @@ -/* - * Copyright 2022 The Backstage Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/** - * NOTE: This is a worker thread function that is stringified and executed - * within a `worker_threads.Worker`. Everything in this function must - * be self-contained. - * Using TypeScript is fine as it is transpiled before being stringified. - */ -export async function buildTypeDefinitionsWorker( - workerData: any, - sendMessage: (message: any) => void, -) { - try { - require('@microsoft/api-extractor'); - } catch (error) { - throw new Error( - 'Failed to resolve @microsoft/api-extractor, it must best installed ' + - 'as a dependency of your project in order to use experimental type builds', - ); - } - - const { dirname } = require('path'); - const { entryPoints, workerConfigs, typescriptCompilerFolder } = workerData; - - const apiExtractor = require('@microsoft/api-extractor'); - const { Extractor, ExtractorConfig, CompilerState } = apiExtractor; - - /** - * All of this monkey patching below is because Material UI has these bare package.json file as a method - * for making TypeScript accept imports like `@material-ui/core/Button`, and improve tree-shaking - * by declaring them side effect free. - * - * The package.json lookup logic in api-extractor really doesn't like that though, as it enforces - * that the 'name' field exists in all package.json files that it discovers. This below is just - * making sure that we ignore those file package.json files instead of crashing. - */ - const { - PackageJsonLookup, - // eslint-disable-next-line @backstage/no-undeclared-imports - } = require('@rushstack/node-core-library/lib/PackageJsonLookup'); - - const old = PackageJsonLookup.prototype.tryGetPackageJsonFilePathFor; - PackageJsonLookup.prototype.tryGetPackageJsonFilePathFor = - function tryGetPackageJsonFilePathForPatch(path: string) { - if ( - path.includes('@material-ui') && - !dirname(path).endsWith('@material-ui') - ) { - return undefined; - } - return old.call(this, path); - }; - - let compilerState; - for (const { extractorOptions, targetTypesDir } of workerConfigs) { - const extractorConfig = ExtractorConfig.prepare(extractorOptions); - - if (!compilerState) { - compilerState = CompilerState.create(extractorConfig, { - additionalEntryPoints: entryPoints, - }); - } - - const extractorResult = Extractor.invoke(extractorConfig, { - compilerState, - localBuild: false, - typescriptCompilerFolder, - showVerboseMessages: false, - showDiagnostics: false, - messageCallback: (message: any) => { - message.handled = true; - sendMessage({ message, targetTypesDir }); - }, - }); - - if (!extractorResult.succeeded) { - throw new Error( - `Type definition build completed with ${extractorResult.errorCount} errors` + - ` and ${extractorResult.warningCount} warnings`, - ); - } - } -} diff --git a/packages/cli/src/lib/builder/config.ts b/packages/cli/src/lib/builder/config.ts index f614581320..41e9dd6906 100644 --- a/packages/cli/src/lib/builder/config.ts +++ b/packages/cli/src/lib/builder/config.ts @@ -151,7 +151,7 @@ export async function makeRollupConfigs( }); } - if (options.outputs.has(Output.types) && !options.useApiExtractor) { + if (options.outputs.has(Output.types)) { const input = Object.fromEntries( scriptEntryPoints.map(e => [ e.name, diff --git a/packages/cli/src/lib/builder/packager.ts b/packages/cli/src/lib/builder/packager.ts index 780f9c2cfe..be9bc9a6ea 100644 --- a/packages/cli/src/lib/builder/packager.ts +++ b/packages/cli/src/lib/builder/packager.ts @@ -21,7 +21,6 @@ import { relative as relativePath, resolve as resolvePath } from 'path'; import { paths } from '../paths'; import { makeRollupConfigs } from './config'; import { BuildOptions, Output } from './types'; -import { buildTypeDefinitions } from './buildTypeDefinitions'; import { PackageRoles } from '@backstage/cli-node'; import { runParallelWorkers } from '../parallel'; @@ -112,10 +111,6 @@ export const buildPackage = async (options: BuildOptions) => { const buildTasks = rollupConfigs.map(rollupBuild); - if (options.outputs.has(Output.types) && options.useApiExtractor) { - buildTasks.push(buildTypeDefinitions()); - } - await Promise.all(buildTasks); }; @@ -131,18 +126,6 @@ export const buildPackages = async (options: BuildOptions[]) => { const buildTasks = rollupConfigs.flat().map(opts => () => rollupBuild(opts)); - const typeDefinitionTargetDirs = options - .filter( - ({ outputs, useApiExtractor }) => - outputs.has(Output.types) && useApiExtractor, - ) - .map(_ => _.targetDir!); - - if (typeDefinitionTargetDirs.length > 0) { - // Make sure this one is started first - buildTasks.unshift(() => buildTypeDefinitions(typeDefinitionTargetDirs)); - } - await runParallelWorkers({ items: buildTasks, worker: async task => task(), diff --git a/packages/cli/src/lib/builder/types.ts b/packages/cli/src/lib/builder/types.ts index 330419235f..7d9c34fe29 100644 --- a/packages/cli/src/lib/builder/types.ts +++ b/packages/cli/src/lib/builder/types.ts @@ -28,5 +28,4 @@ export type BuildOptions = { packageJson?: BackstagePackageJson; outputs: Set; minify?: boolean; - useApiExtractor?: boolean; }; diff --git a/packages/cli/src/lib/packager/createDistWorkspace.ts b/packages/cli/src/lib/packager/createDistWorkspace.ts index e91924dd37..00b8784d6d 100644 --- a/packages/cli/src/lib/packager/createDistWorkspace.ts +++ b/packages/cli/src/lib/packager/createDistWorkspace.ts @@ -206,7 +206,6 @@ export async function createDistWorkspace( logPrefix: `${chalk.cyan(relativePath(paths.targetRoot, pkg.dir))}: `, // No need to detect these for the backend builds, we assume no minification or types minify: false, - useApiExtractor: false, }); } } diff --git a/packages/repo-tools/src/commands/api-reports/api-extractor.ts b/packages/repo-tools/src/commands/api-reports/api-extractor.ts index 13b6acb8fd..ce3e6f5b20 100644 --- a/packages/repo-tools/src/commands/api-reports/api-extractor.ts +++ b/packages/repo-tools/src/commands/api-reports/api-extractor.ts @@ -304,7 +304,6 @@ async function findPackageEntryPoints(packageDirs: string[]): Promise< Array<{ packageDir: string; name: string; - usesExperimentalTypeBuild?: boolean; }> > { return Promise.all( @@ -317,9 +316,6 @@ async function findPackageEntryPoints(packageDirs: string[]): Promise< getPackageExportNames(pkg)?.map(name => ({ packageDir, name })) ?? { packageDir, name: 'index', - usesExperimentalTypeBuild: pkg.scripts?.build?.includes( - '--experimental-type-build', - ), } ); }), @@ -367,11 +363,7 @@ export async function runApiExtraction({ } const warnings = new Array(); - for (const { - packageDir, - name, - usesExperimentalTypeBuild, - } of packageEntryPoints) { + for (const { packageDir, name } of packageEntryPoints) { console.log(`## Processing ${packageDir}`); const noBail = Array.isArray(allowWarnings) ? allowWarnings.some(aw => aw === packageDir || minimatch(packageDir, aw)) @@ -511,7 +503,6 @@ export async function runApiExtraction({ // The root index entrypoint is only allowed @public exports, while /alpha and /beta only allow @alpha and @beta. if ( validateReleaseTags && - !usesExperimentalTypeBuild && fs.pathExistsSync(extractorConfig.reportFilePath) ) { if (['index', 'alpha', 'beta'].includes(name)) { diff --git a/yarn.lock b/yarn.lock index 0242c61e33..13934f039a 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3870,14 +3870,11 @@ __metadata: yn: ^4.0.0 zod: ^3.21.4 peerDependencies: - "@microsoft/api-extractor": ^7.21.2 "@vitejs/plugin-react": ^4.0.4 vite: ^4.4.9 vite-plugin-html: ^3.2.0 vite-plugin-node-polyfills: ^0.14.1 peerDependenciesMeta: - "@microsoft/api-extractor": - optional: true "@vitejs/plugin-react": optional: true vite: