# Installation

# LWC Open Source

Lightning Web Components is an open-source UI framework developed at Salesforce. You can use LWC to customize Salesforce, but you can also use LWC to build any web app.

The LWC compiler and engine code available in the open-source repository is ahead of the code available on the Salesforce Platform. Most, but not all, LWC features are eventually released on the Salesforce Platform.

For more information, see Differences Between Building Lightning Web Components on Lightning Platform and Open Source.

# Getting started

There are many ways to get started using LWC, from the online playground to a fully custom build process to integration into an existing project.

# Online playground

The easiest way to get started with LWC is to use an online playground like StackBlitz. LWC.studio and StackBlitz are third-party products and are subject to their own terms and conditions. Paid options on these sites are not services offered by Salesforce.

# Via Lightning Web Runtime

To create a Lightning Web Components project, use Lightning Web Runtime (LWR).

The tool guides you through a short setup and scaffold a Lightning Web Components project. To use the tool, you must have Node.js.

1. Run this command in your terminal and follow the on-screen instructions.

npm init lwr@latest

2. Create a project directory name or press Enter to accept the default (lwr-project).

3. Select Single Page App.

4. Select LWC.

5. Go to your project folder and run the project.

cd YourProjectName
npm install
npm run start

To include Salesforce platform integrations such as Lightning Design System and Base Lightning Components, see the Lightning Web Runtime Developer Guide

# Via rollup

If you need more control to build your application or if you need to integrate LWC with an existing project, the recommended way is via rollup. In this section, we discuss the minimal setup to create an LWC application using rollup.

To get started, install the following packages first.

npm install --save-dev lwc rollup @lwc/rollup-plugin @rollup/plugin-replace

Add a rollup.config.js at the root of the repository. The rollup configuration file indicates to rollup the application entry point, the output and the desired plugins to apply.

import lwc from '@lwc/rollup-plugin';
import replace from '@rollup/plugin-replace';

export default {
    input: 'src/main.js',

    output: {
        file: 'dist/main.js',
        format: 'esm',
    },

    plugins: [
        replace({
            'process.env.NODE_ENV': JSON.stringify('development'),
        }),
        lwc(),
    ],
};

Add a lwc.config.json file at the root of the repository to instruct the LWC compiler how to resolve your LWC modules.

{
    "modules": [
        {
            "dir": "src/modules"
        }
    ]
}

Now that we are done with the configuration, it's time to create the application entry point. You can add the following content to src/main.js:

import { createElement } from 'lwc';
import App from 'x/app';

const elm = createElement('x-app', { is: App });
document.body.appendChild(elm);

The entry point imports the x/app LWC component. As configured in the lwc.config.json, all the LWC modules should be resolved from src/modules.

To create the x/app component, add the following files: src/modules/x/app/app.js and src/modules/x/app/app.html:

import { LightningElement } from 'lwc';

export default class App extends LightningElement {}

<template>
    <h1>Hello world</h1>
</template>

With everything in place, you can invoke rollup to compile the application by running rollup --config rollup.config.js. Rollup outputs the compiled application code in dist/main.js.

# Via Webpack

An alternative approach to integrate LWC with an existing project is using Webpack. Therefore we provide the LWC Webpack plugin.

To get started, install the following packages first.

npm install --save-dev webpack webpack-cli lwc-webpack-plugin lwc @lwc/module-resolver

Add a webpack.config.js at the root of the repository. The Webpack configuration file indicates to Webpack the desired plugins to apply.

const LwcWebpackPlugin = require('lwc-webpack-plugin');

module.exports = {
    plugins: [new LwcWebpackPlugin()],
};

If you don't have one already, add a lwc.config.json file at the root of the repository to instruct the LWC compiler how to resolve your LWC modules.

{
    "modules": [
        {
            "dir": "src/modules"
        }
    ]
}

Now that we are done with the configuration, it's time to create the application entry point. You can add the following content to src/index.js:

import { createElement } from 'lwc';
import App from 'x/app';

const elm = createElement('x-app', { is: App });
document.body.appendChild(elm);

The entry point imports the x/app LWC component. As configured in the lwc.config.json, all the LWC modules should be resolved from src/modules.

To create the x/app component, add the following files: src/modules/x/app/app.js and src/modules/x/app/app.html:

import { LightningElement } from 'lwc';

export default class App extends LightningElement {}

<template>
    <h1>Hello world</h1>
</template>

With everything in place, you can invoke Webpack to compile the application by running npx webpack build. Webpack outputs the compiled application code in dist/main.js.

# Use Lightning Web Components as Native Web Components

To register a Lightning web component as a custom element, use LightningElement.CustomElementConstructor, which is a static getter that can be accessed by any constructor that extends LightningElement.

In this example, the component name is component, and the namespace is namespace.

import NamespaceComponent from 'namespace/component';
customElements.define('namespace-component', NamespaceComponent.CustomElementConstructor);
// using tagName <namespace-component>
document.body.appendChild(document.createElement('namespace-component'));

In native shadow components, slotted content is preserved in top-level CustomElementConstructor elements.

For example, this top-level <slot> element in an index.html file includes slotted content.

<c-custom-slot>
  <div class="slotted">Pre-existing slot content</div>
</c-custom-slot>

The component renders in the DOM like this. It retains the original slotted content.

<c-custom-slot>
  #shadow-root (closed)
  |  <slot>
  |    <div class="slotted">Pre-existing slot content</div>
  |  </slot>
</c-custom-slot>

To package and distribute your component, see Module Resolution.

# Tools

To develop Lightning web components, you can use just about any code editor and tools.

For code formatting, we recommend Prettier. Prettier supports HTML, CSS, and JavaScript, which are the files you write to create Lightning web components.

To install and use Prettier, see the official documentation. If you're using Git, it's a good idea to use a pre-commit hook to ensure that code is formatted before it's committed to source control.

To configure Prettier, add a configuration file to your project. To correctly format HTML templates with Prettier, set the parser to lwc. The parser is just HTML, but it tells Prettier not to add quotes around template properties in HTML attributes as required by LWC.

The following example sets all HTML files to use the lwc parser.

{
    "overrides": [
        {
            "files": "*.html",
            "options": { "parser": "lwc" }
        }
    ]
}

# Recipes

The github.com/trailheadapps/lwc-recipes-oss repo includes simple code recipes that teach you how to build apps. The recipes are used as code examples throughout this developer guide.

git clone https://github.com/trailheadapps/lwc-recipes-oss.git
cd lwc-recipes-oss

You can view some of the recipes in the Lightning Web Components recipes app: recipes.lwc.dev.

# Playground

The simplest recipe is the helloWorld component. The name property in the component's JavaScript class binds to the component's HTML template. Change World to Earth to see the binding in action.

Add another property in helloWorld.js.

@api greeting = 'Welcome to Lightning Web Components!'

Don't forget to add {greeting} in the helloWorld.html template.

The @api decorator makes the name property public. Because the name and greeting properties are public, a component that consumes the helloWorld component can set their values.

If we remove @api, the property still binds to the HTML template but it's private. To see for yourself, remove @api.

To learn more, see HTML Templates.

# Supported Browsers

# Supported JavaScript

To develop Lightning web components, use the latest versions of JavaScript. You can use any JavaScript feature that the browser supports.

The Salesforce engineers who developed Lightning Web Components are contributing members of the Ecma International Technical Committee 39 (TC39), which is the committee that evolves JavaScript. Salesforce is also a member of the World Wide Web Consortium (W3C).

This developer guide explains how to develop Lightning web components and documents the directives, decorators, and lifecycle hooks that are unique to LWC.

This developer guide doesn’t document standard JavaScript or teach JavaScript fundamentals. Standard JavaScript is documented in the Mozilla Developer Network (MDN) JavaScript Reference. If you’re looking for documentation for a function, try MDN first. For example, if you’re looking for information about addEventListener(), use MDN.

# TypeScript Support for LWC OSS Projects (Developer Preview)

Beginning in LWC OSS v7.0.0, you can author Lightning web components (LWCs) with TypeScript v5.4.5 and later. You can also convert existing JavaScript components to TypeScript.

# Why Should I Develop LWCs with TypeScript?

TypeScript is a superset of JavaScript that improves developer productivity and code quality. It supports build-time type checking, which helps catch errors in your code and improves code reliability. To boost code discoverability and quality, use type-based auto-completion and static type analysis in development environments like Visual Studio Code (VS Code). Other benefits of TypeScript development include greater type safety and easier code maintainability.

# Enable TypeScript Support for LWC OSS Projects

In your project's root directory, verify that a tsconfig.json file exists. If you don't have this file already, create one.

Open tsconfig.json and set the target compiler option to "ESNext". Then, review the module to ensure it doesn't use experimental decorators. You should also make sure the experimentalDecorators compiler option in tsconfig.json is unset or set to false.

{
  "compilerOptions":
  {
    "experimentalDecorators": false,
    "target": "ESNext"
  }
}

Finally, set up TypeScript module resolution. For LWC OSS projects, you have to manually set the paths compiler option in your tsconfig.json file to the module specifier and its resolved path.

{
  "compilerOptions":
  {
    "paths": { "myNamespace/myComponent": ["./modules/myNamespace/myComponent/myComponent.ts"]}
  }
}

# Add TypeScript to Your Project

You can add TypeScript to your OSS project via the Node Package Manager (npm) registry. We recommend running this code on the command line to download TypeScript and set a project dependency on the typescript package in your package.json.

npm install typescript --save-dev

# Convert a JavaScript Component to TypeScript

Do you have a LWC that you want to convert to TypeScript? Follow these steps to update your component.

1. In the component folder, change the component to TypeScript by changing the extension of the script file from .js to .ts.
2. Run the TypeScript compiler and resolve any compilation errors that occur.

To resolve any errors that occur during this process, see Migrating from JavaScript: Moving to TypeScript Files.

# Ambient Modules

If your OSS project uses a build-in module that doesn't have a source file, you can declare an ambient module and define the type yourself. Here's an example of an ambient module for the VendorButton class:

declare module "vendor/button" {
  import { LightningElement } from "lwc";
  export class VendorButton extends LightningElement {
    handleClick(event: ClickEvent): void;
    label?: string;
  }
}

We're working on creating new types for first-party Salesforce modules. For more information, see Salesforce Lightning Types.

# Salesforce Lightning Types

You can download and use type definitions for Salesforce packages via the @salesforce/lightning-types Node package. For a complete list of types in this package, see NPM: @salesforce/lightning-types.

While TypeScript support for LWC is in developer preview, the types in @salesforce/lightning-types are limited. We're working on adding more type definitions to this package.

# Install the Lightning Types Package

First, install @salesforce/lightning-types with your preferred Node package manager.

npm install @salesforce/lightning-types
# OR
yarn add @salesforce/lightning-types

Then, create a new TypeScript file in your project that imports typings from the package. In this example, the file is nested in the types directory.

import "@salesforce/lightning-types";

Finally, in your project's tsconfig.json file, make sure you add a reference to your new .d.ts file.

{
  "compilerOptions": {
    // ...
  },
  "include": ["src", "types"],
}

Now you can import Salesforce Lightning types like this:

import LightningInput from "lightning/input";

# Considerations and Limitations

For now, LWC OSS support for TypeScript excludes these use cases.

• Using TypeScript with the Salesforce CLI
• Source map debugging using TypeScript
• Non-Salesforce types
• Type definitions for custom Salesforce fields and objects

# Release Notes

The LWC Release Notes are on GitHub: github.com/salesforce/lwc/releases.