@webruntime/compiler v1.61.4

Lightning Web Runtime :: Compiler

Table of contents

• Introduction
• Background
  • Definitions
  • Rollup plugins
• APIs
  • compile()
    • Compiler input
    • Compiler output
• Examples
  • Simple application
  • LWC
  • JavaScript library
  • Full Compiler config object
• Container config mappings

Introduction

The Lightning Web Runtime Compiler is a pluggable Rollup-based bundler for off-core LWC-based applications.

The Web Runtime Compiler extends the LWC/Rollup bundling functionality with the ability to inject container services, which can then participate in the compilation lifecycle phase.

Background

Definitions

Lightning Web Runtime: A LWC application runtime.

container: Initializes and builds the set of container services which make up an application.

container service: A service plugin, which can be (1) addressed and (2) hook into various container lifecycle phases.

specifier: A string import value (eg: import('app/home'), import('lodash')).

pivot: A way to specify when a particular component/module may be loaded relative to some context (eg: 'mobile' vs 'desktop', locale, etc).

Rollup plugins

Along with custom plugins, these Rollup plugins are automatically included and used by the Compiler:

• @lwc/rollup-plugin
• rollup-plugin-node-resolve
• rollup-plugin-commonjs
• If compat mode is on: rollup-plugin-compat
• If minify mode is on: terser is used

APIs

compile()

The Web Runtime Compiler exposes one main function:

async function compile(input):Promise<output>

It takes in a configuration object, and returns a Promise to its output.

Compiler input

• LWC compiler options:

  • name (string, required): component name.
  • namespace (string, required): component namespace.
  • files ({ string: string, ...}, required): key/value pairs where each key is a file path and its value is a string containing the file contents.
  • baseDir (string, optional, default = ""): a directory prefix which contains contains the components being compiled.
  • lwcOptions (object, optional): pass in a customized LWC Rollup plugin config object, which gets merged with a default object. The following options are available (all are optional): rootDir, modules, exclude, stylesheetConfig, and experimentalDynamicComponent.
  • outputConfig (object[], optional):
    • compat (boolean, optional, default = false): true indicates browser compatibility mode.
    • minify (boolean, optional, default = false): true if the bundle should be minified.
    • sourcemap (boolean, optional, default = false): true if a source map should be generated.
    • env (object, optional, default = { NODE_ENV: 'development' }):
      • NODE_ENV (string, required) = node environment string (eg: 'production', 'development', etc).

• Rollup options:

  • input (string, optional, default = ${namespace}/${name}): the input path for the bundle, similar to Rollup's input.
  • external (string[], optional, default =['lwc']): list of dependencies that should not be included in the bundled output, similar to Rollup's external.
  • format (string, optional, default = 'amd'): type of output ('amd', 'cjs', 'esm', 'iife', 'umd') similar to Rollup's output.format.
  • formatConfig (object, optional, default = { id: namespace + '/' + name, define: undefined }):
    • amd (object):
      • define (string): function to use in place of define, similar to Rollup's output.amd.define

• Web Runtime options:

  • plugins (Plugin[], optional, default = []): array of Rollup plugins to use.
  • inlineConfig (object[], optional, default = []): describes the exclusion patterns for each module descriptor; array of objects with the following properites:
    • descriptor (string | glob, required): specifier which should have all dependencies inlined, EXCEPT for those in the exclude array.
    • exclude (string[] | RegExp | glob, optional, default = []): array of specifiers which should be excluded from being inlined.

Compiler output

The Compiler's output uses the same format as the LWC compiler.

• output (object):
  • success (boolean): true if the Compiler encountered no fatal errors.
  • diagnostics (CompilerDiagnostic[]): array of error and warning information.
  • result:
    • code (string): the resulting bundled code.
    • map (* | null): the generated source map, if requested.
    • outputConfig (object | undefined): same object passed in as [Compiler input](#compiler-input).outputConfig.
  • version (string): the version of the Compiler which bundled this code.

Examples

Simple application

Creating a bundle for an LWC application. Components are stored in ./src.

import { compile } from '@webruntime/compiler';
import * as path from 'path';

const options = {
    name: 'main',
    namespace: 'any',
    external: ['lwc'],
    baseDir: path.join(__dirname, 'src'),
    files: {
        'any/main': `
            import { createElement } from 'lwc';
            import App from 'x/app';
            const element = createElement('x-app', { is: App });
            document.body.appendChild(element);
        `,
    },
};

const { success, diagnostics } = await compile(options);

if (!success) {
    for (let diagnostic of diagnostics) {
        console.error(`${diagnostic.level}: ${diagnostic.message}`);
    }
}

LWC

Creating a bundle for a LWC stored in the files object:

import { compile } from '@webruntime/compiler';

const options = {
    name: 'lwc',
    namespace: 'my',
    external: ['lwc'],
    files: {
        'my/lwc.js': `
            import { LightningElement } from 'lwc';
            export default class Lwc extends LightningElement {}
        `,
        'my/lwc.html': '<template>lwc</template>',
        'my/lwc.css': ':host { font-size: 16px; }',
    },
};

const { success, code } = await compile(options);

console.log('The bundle is: ', success ? code : 'a failure');

// Output:
// The bundle is: define('my/lwc', ['lwc'], function (lwc) { ... });

JavaScript library

Create a non-LWC bundle. The JavaScript entry point must live in the files object:

import { compile } from '@webruntime/compiler';
import * as fs from 'fs';
import * as path from 'path';

const filePath = path.join(__dirname, 'src', 'x', 'file.js');
const fileContents = fs.readFileSync(filePath).toString();
export const options = {
    name: 'file',
    namespace: '',
    files: {
        'file.js': fileContents,
    },
};

const { code = '' } = await compile(options);
export default code;

Full Compiler config object

{
    // LWC
    name: 'cmp',
    input: 'x',
    files: {
        'logger.js': 'export const logger = console.log;'
    },
    baseDir: path.join(__dirname, 'apps'),
    lwcOptions: {
        stylesheetConfig: {
            customProperties: {
                resolution: {
                    type: 'module',
                    name: '@salesforce/cssvars/customProperties',
                },
            },
        },
        experimentalDynamicComponent: {
            loader: '',
            strictSpecifier: true,
        },
    },
    outputConfig: {
        compat: true,
        minify: true,
        sourcemap: true,
        env: { NODE_ENV: 'production' }
    },

    // Rollup
    external: [
        'lwc',
        'force/lds',
        'wire-service'
    ],
    format: 'amd',
    formatConfig: {
        amd: { define: 'loader.addModule' }
    },

    // Web Runtime
    plugins: [
        {
            plugin: 'src/rollup/global-rollup.js',
            config: {
                globals: {
                    'lodash': '_',
                },
            },
        },
    ],
    inlineConfig: [
       { descriptor: 'view/*', exclude: ['view/faq', 'wire-service'] },
       { descriptor: 'x/foo', exclude: ['@salesforce/**'] }
    ],
}

Container config mappings

Compiler configuration options are gathered from different areas, including:

• the calling service, possibly via a Rollup plugin (service)
• the Container config object (containerConfig)

name: service
namespace: service
files: service
baseDir: containerConfig.moduleDir
stylesheetConfig: service or containerConfig.compilerConfig.lwcOptions
experimentalDynamicComponent: service or containerConfig.compilerConfig.lwcOptions
outputConfig: containerConfig.compilerConfig.outputConfig[mode]
external: containerConfig.externals, containerConfig.preloadModules, compilerConfig.external and exclusionsFrom(config.bundle)
format: service or container defaults
formatConfig: containerConfig.compilerConfig.formatConfig
plugins: service or container defaults
inlineConfig: containerConfig.bundle