Skip to main content

Migrate to v2.0

Configuration#

Beemo configuration has moved#

Previously, configuration was either defined in a root configs/beemo.js file, or a beemo block within package.json. Configuration must now be defined in .config/beemo.ts (or .js, .json, .yaml, etc). Package level config has been removed entirely.

.config/beemo.ts
export default {
module: '<config-module>',
};

Driver overrides have been removed from package.json#

The ability to configure drivers in a beemo.<driver> block within package.json has been removed. Instead, configure the driver at .config/beemo/<driver>.ts (or .js).

package.json
// Before
{
"beemo": {
"eslint": {
"rules": {
"no-console": "off"
}
}
}
}
.config/beemo/eslint.ts
// After
import { ESLintConfig } from '@beemo/driver-eslint';
const config: ESLintConfig = {
rules: {
'no-console': 'off',
},
};
export default config;

Drivers configuration structure has changed#

When configuring drivers with the drivers setting, either supply a list of names.

.config/beemo.ts
export default {
module: '<config-module>',
drivers: ['babel', 'jest'],
};

Or a tuple with a name and an options object.

.config/beemo.ts
export default {
module: '<config-module>',
drivers: [
'babel',
[
'jest',
{
env: {
NODE_ENV: 'test',
},
},
],
],
};

Or if you need more control, an object of names that map to booleans (enable or disable the driver), or an options object.

.config/beemo.ts
export default {
module: '<config-module>',
drivers: {
babel: true,
jest: {
env: {
NODE_ENV: 'test',
},
},
},
};

The old format of mixing strings and objects within a list is no longer supported. For more information on these formats, check out the official Boost documentation on plugins.

Beemo#

File and type have moved#

The Beemo class instance is no longer default exported from @beemo/core. It can now be accessed from the named Tool class export, or the BeemoTool type alias export.

// Before
import Beemo from '@beemo/core';
// After
import { Tool } from '@beemo/core';

Logging has been removed#

All logging methods have been removed. Use the native console instead.

// Before
beemo.log();
beemo.log.error();
beemo.console.log();
// After
console.log();
console.error();

Workspace methods have moved#

Methods relating to project workspaces have moved to the project class property. The APIs of these methods may have also changed, so please refer to their TypeScript types.

// Before
beemo.getWorkspacePaths();
// After
tool.project.getWorkspacePaths();

Driver and script management has changed#

Drivers and scripts have moved to a registry based pattern, resulting in changes to the Tool API.

// Before
beemo.getPlugin('script', 'build');
beemo.getPlugin('driver', 'babel');
beemo.isPluginEnabled('driver', 'typescript');
// After
tool.scriptRegistry.get('build');
tool.driverRegistry.get('babel');
tool.driverRegistry.isRegistered('typescript');

Driver and script modules must export a factory function and have a name property#

If you're using custom driver and script modules, they must now default export a function that returns a class instance, instead of exporting a class declaration. Furthermore, all driver and script instances must have a name property (which is the name of the NPM module).

// Before
export default class CustomDriver extends Driver<CustomConfig, CustomOptions> {}
// After
class CustomDriver extends Driver<CustomConfig, CustomOptions> {
readonly name = 'npm-module-name-driver';
}
export default (options: CustomOptions) => new CustomDriver(options);

Contexts#

With the migration from yargs to @boost/args, the args object structure has changed, as well as any terminology.

Options are now located in multiple locations#

Options are either known or unknown, depending on the CLI command being ran. Known options are now accessed from args.options, while unknown options from args.unknown. Since unknown options are well, unknown, we have no information on what type of value they should be, so all unknown option values are always strings.

// Before
context.args.clean;
// After
context.args.options.clean;
context.args.unknown.clean;

To avoid having to check both of these locations, a new Context#getRiskyOption() method has been provided. It will return the known option if it exists, otherwise unknown, and null if neither exists.

context.getRiskyOption('clean');

However, this method is risky, as denoted by its name. For unknown options, empty string values are converted to true, as they are treated as flags (--clean). If you want to avoid the conversion, pass true as a 2nd argument.

Positional args are now referred to as params#

The title is self-explanatory. Args are now called params, and the argv list is now accessed from args.params instead of args._.

// Before
context.args._;
context.addArg('./src');
context.addArgs(['foo', 'bar']);
// After
context.args.params;
context.addParam('./src');
context.addParams(['foo', 'bar']);

Drivers#

Jest: Peer dependency on Babel has been removed#

The @beemo/driver-babel peer dependency has been removed from the Jest driver's package.json, but the Babel config will still be automatically generated when running Jest if the Babel driver has been enabled.

If you're using Babel to transform files within your Jest tests, be sure to install both driver dependencies manually.

TypeScript: The --reference-workspaces option has been removed#

In previous versions, the --reference-workspaces CLI option would automatically generate project references in the root tsconfig.json, and a tsconfig.json in each package folder. Going forward, root project references will now be linked automatically if a project is workspaces enabled (Yarn workspaces, etc) instead of requiring a CLI option.

TypeScript: Package project reference linking has moved to a new command#

As mentioned above, project references were automatically linked when running the TypeScript driver with --reference-workspaces. However, this process was rather heavy and only needed to be ran when adding or removing packages, or changing dependencies. Because of this, package-level project reference linking has moved to a new command, beemo typescript:sync-project-refs.

This new command will only update the tsconfig.json within each package, as the root tsconfig.json is still updated when running beemo typescript.

Scripts#

Script arguments are now based on @boost/args#

To support the new functionality provided by @boost/args, the args() method has been renamed to parse(), and the return type/structure has changed to ParserOptions. Furthermore, the 2nd argument to execute() has updated to the type/structure of Arguments.

// Before
class BuildScript extends Script {
args() {
return {
string: ['workspaces'],
default: {
workspaces: '',
},
};
}
}
// After
class BuildScript extends Script {
parse() {
return {
options: {
workspaces: {
description: 'Glob pattern to find workspaces',
type: 'string',
},
},
};
}
}

Script tasks have been removed#

The executeTasks() and task() methods have been removed. If you would like similar functionality, we suggest using the @boost/pipeline package directly.

TypeScript#

Only including important type changes.

  • Migrated Arguments to @boost/args structure.
  • Removed the generic from Tool (formerly Beemo).
  • Removed:
    • BeemoPluginRegistry
    • ExecuteType
    • ExecuteQueue
    • StdioType