README.md

Factory

This is used to aggregate all the plugins and expose them to the bundler.

Note

We use unplugin to support many different bundlers.

• Internal Plugins
  • Build Report
  • Bundler Report
  • Git
  • Injection
• Logger
• Global Context

Internal Plugins

These are the plugins that are used internally by the factory. Most of the time they will interact via the global context.

Build Report

This will populate context.build with a bunch of data coming from the build.

📝 Full documentation ➡️

Bundler Report

A very basic report on the currently used bundler.
It is useful to unify some configurations.

📝 Full documentation ➡️

Git

Adds repository data to the global context from the buildStart hook.

📝 Full documentation ➡️

Injection

This is used to prepend some code to the produced bundle.
Particularly useful if you want to share some global context, or to automatically inject some SDK.

📝 Full documentation ➡️

Logger

If you need to log anything into the console you'll have to use the global Logger. Simply add it to your getMyPlugins function and run yarn cli integrity to update the factory.

// ./packages/plugins/my-plugin/index.ts
[...]

export const getMyPlugins = (context: GlobalContext, log: Logger) => {
    log.debug('Welcome to my plugin');
    [...]
};

Then you can either use one of the level logger methods:

logger.warn('This is also a warning');
logger.error('This is an error');
logger.info('This is an info');
logger.debug('This is a debug message');

You can also create a "sub-logger" when you want to individually identify logs from a specific part of your plugin.
Simply use log.getLogger('my-plugin') for this:

export const getMyPlugins = (context: GlobalContext, log: Logger) => {
    log.debug('Welcome to the root of my plugin');
    return [
        {
            name: 'my-plugin',
            setup: (context: PluginContext) => {
                const subLog = log.getLogger('my-plugin');
                subLog.info('This is a debug message from one of my plugins.');
            },
        },
    ];
};

Global Context

A global, shared context within the build plugins ecosystem.
It is passed to your plugin's initialization, and is mutated during the build process.

type GlobalContext = {
    // Mirror of the user's config.
    auth?: {
        apiKey?: string;
    };
    // More details on the currently running bundler.
    bundler: {
        name: string;
        fullName: string; // Including its variant.
        outDir: string; // Output directory
        // Added in `buildStart`.
        rawConfig?: any;
        variant: string; // Major version of the bundler (webpack 4, webpack 5), empty string otherwise.
    };
    // Added in `writeBundle`.
    build: {
        errors: string[];
        warnings: string[];
        // The list of entries used in the build.
        entries ? : {
            filepath: string;
            inputs: Input[],
            name: string;
            outputs: Output[]
            size: number;
            type: string,
        } [];
        // The list of inputs used in the build.
        inputs ? : {
            filepath: string;
            dependencies: Input[];
            dependents: Input[]
            name: string;
            size: number;
            type: string,
        } [];
        // The list of outputs generated by the build.
        outputs ? : {
            filepath: string;
            name: string;
            size: number;
            type: string,
            // Sourcemaps will use Outputs as their Inputs.
            inputs: (Input | Output)[]
        } [];
        start?: number;
        end?: number;
        duration?: number;
        writeDuration?: number;
    };
    cwd: string;
    // Added in `buildStart`.
    git?: {
        hash: string;
        remote: string;
        trackedFilesMatcher: [TrackedFilesMatcher](/packages/plugins/git/trackedFilesMatcher.ts);
    };
    inject: (item: { type: 'file' | 'code'; value: string; fallback?: @self }) => void;
    start: number;
    version: string;
}

Note

Some parts of the context are only available after certain hooks:

• context.bundler.rawConfig is added in the buildStart hook.
• context.build.* is populated in the writeBundle hook.
• context.git.* is populated in the buildStart hook.