TypeScript Type Definitions for LWC (Developer Preview)

Beginning in Winter '25, you can use Salesforce type definitions with TypeScript v5.4.5 to develop Lightning web components (LWCs). To use type definitions in your LWC project, follow these steps:

1. Enable TypeScript Support
2. Add the TypeScript Package
3. Compile TypeScript Components to JavaScript

For a list of available Salesforce types, see Salesforce Lightning Types.

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.

Before you can add TypeScript files to your LWC project, you have to configure your project to support TypeScript code.

First, in your project's settings.json, set the feature flag salesforcedx-vscode-lwc.preview.typeScriptSupport to true.

Save your changes to automatically create a tsconfig.json file in the lwc folder, or the folder that contains your project's components. If you don't see a new tsconfig.json, restart VS Code.

Open tsconfig.json and set these options in the compilerOptions section:

• target: Set this option to "ESNext".
• experimentalDecorators: If you use the VS Code extension, set this option to true. If not, set it to false.
• module: Set this option to a value that emits ECMAScript modules. We recommend the value "Preserve" for maximum compatibility with the full Node.js ecosystem, but you can alternatively use "ESNext" or "NodeNext". For more details, see the official TypeScript documentation for module.

Here's an example of a complete tsconfig.json file with the correct compilerOptions settings for TypeScript support.

Add TypeScript to your project via the npm registry. The following npm command downloads TypeScript and sets a project dependency on the typescript package in your package.json. The minimum supported version is v5.4.5.

The LWC compiler doesn't compile TypeScript files. So before you can deploy TypeScript LWCs, you must convert your TypeScript code to Javascript.

After you deploy your components, the Salesforce platform doesn't store your TypeScript code. Your TypeScript files exist only on the client-side: either on your local machine or in your source control system.

For example, here's an example of what a deployed TypeScript component (contact) looks like in your local project directory.

To convert all of your TypeScript code to JavaScript, you can run this tsc on the command line for your entire lwc directory.

This command generates a JavaScript version of each of your TypeScript components. Here's an example of the compiled component folder output for the sample component contact.

For more guidance on managing TypeScript and JavaScript code in your project, see Use a Source Control System.

Do you have a JavaScript LWC in your project's lwc folder 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.

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. You can see a complete list of available types in the package README.

The VS Code Salesforce Extension Pack automatically installs type definitions from the @salesforce/lightning-types and lwc npm packages in your project. These type definitions support wire adapters like lightning/uiRecordApi and lightning/uiObjectInfoApi. Type definitions provided by the Extension Pack are subject to change, and they may be moved to the lightning-types package after the developer preview.

If you aren't using VS Code, you have to manually install these packages in your project.

First, we recommend installing @salesforce/lightning-types using npm, like this:

Then, create a new d.ts file in your project that imports all the type definitions from @salesforce/lightning-types. This sample file salesforce.d.ts contains the recommended import statement, and the file is nested in its project's types directory.

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

Now, in your TypeScript component files, you can import Salesforce Lightning types like this:

If your project uses a component that doesn't have type definitions available, you can declare an ambient module and define your own types. Here's an example of an ambient module for the VendorButton class:

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

After you integrate TypeScript into your LWC project, be aware of these restrictions.

You're wholly responsible for managing custom TypeScript configurations and TypeScript compiler upgrades for your project. To learn what's new for each release of TypeScript, review the Release Notes in TypeScript Documentation.

If you integrate TypeScript into your project, we recommend you manage your code using a source control system like Git instead. TypeScript code isn't stored on the Salesforce platform. You can't deploy TypeScript code or retrieve it from the platform.

For now, LWC 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