Wondering what’s next for npm?Check out our public roadmap! »

    @lwc/compiler
    TypeScript icon, indicating that this package has built-in type declarations

    1.18.0 • Public • Published

    LWC Compiler

    @lwc/compiler is an open source project that enables developers to take full control of processing a single Lightning Web Components module for runtime consumption.

    Installation

    yarn add --dev @lwc/compiler

    APIs

    compile

    import { compile } from '@lwc/compiler';
    
    const options = {
        name: 'foo',
        namespace: 'x',
        files: {
            'foo.js': `
              import { LightningElement } from 'lwc';
              export default class Foo extends LightningElement {}
            `,
            'foo.html': `<template><h1>Foo</h1></template>`,
        },
    };
    
    const {
        success,
        diagnostics,
        result: { code },
    } = await compile(options);
    
    if (!success) {
        for (let diagnostic of diagnostics) {
            console.log(diagnostic.level + ':' + diagnostic.message);
        }
    }
    
    return code;

    Parameters:

    • options (object) - the object which specifies compilation source and output shape
      • name (string, required) - component name.
      • namespace (string, required) - component namespace.
      • files (BundleFiles, required) - key value pairs where each key is one of the bundle files and its value is a string value of the file content.
      • baseDir (string, optional) - An optional directory prefix that contains the specified components. Only used when the component that is the compiler's entry point.
      • stylesheetConfig (StylesheetConfig, optional) - css configuration.
      • outputConfig (OutputConfig, optional) - compiler output configuration. Dictates the shape of the bundle output (ex: bundle compiled for production mode, minified).

    Return

    • output (object) - the object with the following fields:
      • success (boolean) - compilation results (true only if all compilation steps were successful).
      • diagnostics (Diagnostic[]) - an array of compilation Diagnostic objects (ex: warnings, errors)
      • result (BundleResult) - an object containing compiled code and configuration used during compilation;
      • version (string) - the version of compiler used for current compilation.

    transform

    Transform the content of individual file for manual bundling.

    import { transform } from '@lwc/compiler';
    
    const source = `
        import { LightningElement } from 'lwc';
        export default class App extends LightningElement {}
    `;
    
    const filename = 'app.js';
    
    const options = {
        namespace: 'c',
        name: 'app',
    };
    
    const { code } = await transform(source, filename, options);

    Parameters:

    • source (string, required) - the source to be transformed can be the content of javascript, HTML, CSS.
    • filename (string, required) - the source filename with extension.
    • options (object, required) - the transformation options. The name and the namespace of the component is a minimum required for transformation.

    Return

    • code (string)- the compiled source code.
    • map (null) - not currently supported.

    version

    import { version } from '@lwc/compiler';
    
    console.log(version);

    Return

    • version (string) - the current version of the compiler ex: 0.25.1.

    Compiler Interface

    Configuration Interface

    Compiler can be configured to produce one bundle at a time with the following configurations:

    export interface CompileOptions {
        name: string;
        namespace: string;
        files: BundleFiles;
        /**
         * An optional directory prefix that contains the specified components
         * files. Only used when the component that is the compiler's entry point.
         */
        baseDir?: string;
        stylesheetConfig?: StylesheetConfig;
        outputConfig?: OutputConfig;
    }
    
    export interface TransformOptions {
        name: string;
        namespace: string;
        /**
         * An optional directory prefix that contains the specified components
         * files. Only used when the component that is the compiler's entry point.
         */
        baseDir?: string;
        stylesheetConfig?: StylesheetConfig;
        outputConfig?: OutputConfig;
    }
    
    export interface BundleFiles {
        [filename: string]: string;
    }
    
    export interface StylesheetConfig {
        customProperties?: CustomPropertiesConfig;
    }
    
    export interface OutputConfig {
        env?: { [name: string]: string };
        compat?: boolean;
        minify?: boolean;
        resolveProxyCompat?: OutputProxyCompatConfig;
    }
    
    export type OutputProxyCompatConfig =
        | { global: string }
        | { module: string }
        | { independent: string };

    Compiler Configuration Example

    const config = {
        name: 'foo',
        namespace: 'x',
        files: {
            foo: `
              import { LightningElement, track } from 'lwc';
              export default class Foo extends from LightningElement {
                @track
                title = 'Foo Title';
              }
            `,
            'foo.html': `<template><h1>{title}</h1></template>`,
        },
        outputConfig: {
            env: {},
            minify: false,
            compat: false,
            format: 'amd',
        },
    };

    The compiler configuration object is always normalized to apply necessary defaults. However, the bundle configuration is always a required parameter, which specifies a module name, namespace, type of the platform (used to determine linting rules), and a map of files to be compiled. Please note that the file value should be a string. If no outputConfig specified, compiler will produce a single result item with the following default output configuration:

    {
        outputConfig: {
            compat: false,
            minify: false,
            env: {
                NODE_ENV: 'development'
            },
        },
        stylesheetConfig: {
            customProperties: {
                resolution: { type: 'native' }
            }
        }
    }

    Compiler Output Interface

    export interface CompilerOutput {
        success: boolean;
        diagnostics: Diagnostic[];
        result?: BundleResult;
        version: string;
    }
    
    export interface BundleResult {
        code: string;
        map: null;
        outputConfig: NormalizedOutputConfig;
    }
    
    export interface ModuleImportLocation {
        name: string;
        location: Location;
    }
    
    export interface NormalizedOutputConfig extends OutputConfig {
        compat: boolean;
        minify: boolean;
        env: {
            [name: string]: string;
        };
    }

    Compiler Transformation and Bundling:

    screen shot 2018-08-23 at 4 14 28 pm

    Transformations

    There are several transformational phases that take place during compilation followed by a bundling phase. The Compiler utilizes Rollup.js and its plugin system, which enables us to change its behavior at key points in the bundling process. LWC compilation pipeline consists of the following plugins:

    Replace - replace code (ex: process.env.NODE === ‘production’ will be replaced with true or false depending on the mode).

    Module Resolution - ensure that each local import in the component can be resolved.

    Transformation - apply LWC specific transformation to js, html, and css files.

    Compat - apply the compatibility transformation (ex: polyfills for older browsers).

    Minify - apply minification for ‘production’ mode code.

    These transformation may or may not be applied depending on the mode values specified in the compiler configuration object.

    Bundling

    The final phase of the compilation pipeline is bundling. During bundling, Rollup will ‘statically analyze and optimize the code you are importing, and will exclude anything that isn't actually used. This allows you to build on top of existing tools and modules without adding extra dependencies or bloating the size of your project’. The end result of the bundler is a single javascript file in a specified format - ‘amd’ by default.

    Keywords

    none

    Install

    npm i @lwc/compiler

    DownloadsWeekly Downloads

    21,394

    Version

    1.18.0

    License

    MIT

    Unpacked Size

    72.1 kB

    Total Files

    45

    Homepage

    lwc.dev/

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar