# 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 way 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 webcomponents.dev.

# Via create-lwc-app

To create a brand new Lightning Web Components project, use create-lwc-app.

The tool guides you through a short setup and scaffold a Lightning Web Components project. To use the tool, you must have npx, which is a package runner.

npx create-lwc-app my-app
cd my-app

npm run watch       # Start local server with file watcher
npm run build       # Build application in production mode

For more details, see the create-lwc-app README.

# 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.

# 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'));

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.

# Release Notes

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