LWC Platform Compiler

Platform compiler is essentially a lwc compiler wrapper that enables multi-bundle compilation for dev and prod modes, reference report, class documentation, and linting.

This package is used by SFDX to help with development of LWCs in a SFDX project. It is NOT meant to be consumed directly by LWC developers. If you need the LWC Compiler in non-SFDX context, visit https://github.com/salesforce/lwc.

Platform Compiler Interface

Invocation example:

const compilationReport = await compile({
    bundle: {
        namespace: 'x',
        name: 'foo',
        type: 'platform',
        files: {
            'foo.js': `
                import { api, LwcElement } from 'lwc';

                export default class Test extends LwcElement {
                    @api name;
                }
            `,
            'foo.html': `
                <template>
                    <h1>{name}</h1>
                </template>
            `,
        },
    },

    outputConfigs: [
        {
            minify: false,
            env: {
                NODE_ENV: 'development',
            },
        },
    ],
});

const { success, results, diagnostics, metadata, version } = compilationReport;

The compiler configuration object is always normalized to apply necessary defaults. However, the bundle configuration is a required input, 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 outputConfigs specified, compiler will produce a single result item with the following default output configuration:

{
    minify: false,
    env: {
        NODE_ENV: 'development'
    },
}

However, if necessary, the compiler can be configured to produce multiple bundles in a single invocation. To achieve this, simply add an additional OutputConfig object in the outputConfigs array. Each OutputConfig object will correspond to the BundleResult object produced in the CompilerReport results.

The above invocation produces the following output:

const { success, results, diagnostics, metadata, version } = compilationReport;

Please see compiler output breakdown in the Output Interface section below.

Invocation Interface

interface CompilerConfig {
    /** The module to compile */
    bundle: Bundle;

    /**
     * Array of compilation configurations - mode, env, etc.
     * Use this to request compilation for multiple modes.
     */
    outputConfigs?: OutputConfig[];
}

interface Bundle {
    /** The module name */
    name: string;

    /** The module namespace */
    namespace: string;

    /** Specifies type of the bundle ( internal || platform ) - used by linter to use appropriate set of rules */
    type: string;

    /** An object associating a relative file in the module folder to it's source code */
    files: {
        [filename: string]: string;
    };
}

/**
 * Output configuration - used
 * to configure bundling format, such as mode, env ( dev, prod, prod_debug )
 */
interface OutputConfig {
    minify?: boolean;

    /** Optional env, ex: NODE_ENV = 'production' */
    env?: {
        [key: string]: string;
    };

    /**
     * Optional compat value. If compat is enabled defaults
     * to: { independent: "proxy-compat" }
     */
    resolveProxyCompat?: Optional<Map<String, String>>;
}

interface CustomPropertiesConfig {
    allowDefinition?: boolean; // defaults to false
    resolution?: CustomPropertiesResolution; // defaults { type: 'native' }
}

/** Specifies the custom property resolution strategy defaults to native */
interface CustomPropertiesResolution {
    type: module | native;
    name?: string;
}

Output Interface

/**  Compiler can be invoked one mode at the time */
interface CompilerReport {

    /**
     * Status of the compilation process.
     * The result will be false unless all bundles are successfully compiled
     */
    success: boolean;

    /**
     * Compiler version
     */
    version: string;

    /**
     * List of compilation diagnostics - each objects represents a severity of the issue, its message and location.
     * Diagnostics are collected at each step of compilation, including but not limited to linting, module resolution, and
     * bundling.
     */
    diagnostics: Diagnostic[];

    /**
     * Class documentation
     */
    documentation?: PlatformBundleDoc;

    /**
     * Output metadata - an object with bundle references and decorators ( only one metadata object is produced per report,
     * regardless ).
     */
    metadata?: ReportMetadata;

    /**
     * Compilation results - each bundle corresponds to the supplied OutputConfig. Please note that each BundleResult
     * contains its own OutputConfig object, which represents the configuration used for compiling current bundle.
     */
    results?: BundleResult[];

}

interface PlatformBundleDoc {
    classDescription?: string;
    html?: string;
    metadata?: DocumentationMetadata;
}

interface DocumentationMetadata {
    [key: string]: any;
}

interface ReportMetadata {

    /** The file of external objects the module is referencing */
    references?: Reference[];

    /** Decorators used by the component */
    decorators?: Array<ApiDecorator | TrackDecorator | WireDecorator>
}


interface BundleResult {

    /** Compiled code */
    code: string;

    /** Source map - not yet supported but reserving the name */
    map: null;

    /** List of transformation and bundling diagnostics */
    diagnostics: Diagnostic[];

    /** Bundle metadata - contains importLocations */
    metadata?: BundleMetadata;

    /** Expanded config used during compilation - mode, env, etc.
     * expanded means normalized to include all supported properties
     *
     * output ex:
     * { minify: false, env: { NODE_ENV: 'development' } }
     */
    outputConfig: OutputConfig;

}

interface BundleMetadata {
   importLocations: ImportLocation[];
}

interface ImportLocation {
    name: string;
    location: Location;
}

interface Diagnostic {
    /** Level of the diagnostic */
    level: DiagnosticLevel;

    /** Optional - relative path location of the file in the bundle */
    filename?: string;

    /** Error messages that should be outputted */
    message: string;

    /**
     * Location in the code affected by the diagnostic.
     * This field is optional, for example when the compiler throws an uncaught exception.
     */
    location?: Location;
}

enum DiagnosticLevel {
    /** Unexpected error, parsing error, bundling error */
    Fatal = 0
    ,
    /** Linting error with error level, invalid external reference, invalid import, invalid transform */
    Error = 1,

    /** Linting error with warning level, usage of an API to be deprecated */
    Warning = 2,

    /** Logging messages */
    Log = 3
}

interface Location {
    /** 0-base character index in the file */
    start: number;

    /** Number of character after the start index */
    length: number;
}

interface Reference {
    /** Reference type */
    type: ReferenceType;

    /** Reference id. eg: "MyClass/MyMethod", or "x-foo" */
    id: string;

    /** Optional - relative path location of the file in the bundle */
    filename?: string;

    /** List of occurrences of the reference in the file */
    locations: Location[];
}

type ReferenceType =
      '@salesforce/apexMethod'
    | '@salesforce/client'
    | '@salesforce/community'
    | '@salesforce/component'
    | '@salesforce/contentAssetUrl'
    | '@salesforce/customPermission'
    | '@salesforce/featureFlag'
    | '@salesforce/messageChannel'
    | '@salesforce/i18n'
    | '@salesforce/label'
    | '@salesforce/lds'
    | '@salesforce/module'
    | '@salesforce/resourceUrl'
    | '@salesforce/schema'
    | '@salesforce/site'
    | '@salesforce/user'
    | '@salesforce/userPermission'
    | '@salesforce/komaci'
    | '@salesforce/webstore'
    | 'module';  // default if none of the above types match