Setup

Prerequisites

To follow this guide, it is expected you have node, pnpm and sfdx installed as well as a SFDX Project setup with a valid lwr.config.json file.

Note

If you havn’t already installed the default LWR specific packages, you will need to install them before continuing.

For convenience, here is a list of packages you’ll require if not already installed:

pnpm

pnpm add -D @lwc/engine-dom @lwc/synthetic-shadow @lwrjs/client-modules @lwrjs/config @lwrjs/core @lwrjs/loader @lwrjs/o11y @lwrjs/router @lwrjs/shared-utils @lwrjs/types

npm

npm install @lwc/engine-dom @lwc/synthetic-shadow @lwrjs/client-modules @lwrjs/config @lwrjs/core @lwrjs/loader @lwrjs/o11y @lwrjs/router @lwrjs/shared-utils @lwrjs/types

yarn

yarn add @lwc/engine-dom @lwc/synthetic-shadow @lwrjs/client-modules @lwrjs/config @lwrjs/core @lwrjs/loader @lwrjs/o11y @lwrjs/router @lwrjs/shared-utils @lwrjs/types

We also use both @lukethacoder/lwc-module-resolver and @lukethacoder/lwrjs-lwc-module-provider under the hood to handle greater customisation of folder configuration.

If you are having troubles, checkout the Minimal Config Example or the On Platform Example.

1. Install the package

   Run the following command in your terminal from the root of your SFDX Project to install LWC Garden:

   pnpm

   pnpm add @lwc-garden/core tsx

   Optionally with @lwc-garden/utils

   pnpm add @lwc-garden/core @lwc-garden/utils tsx

   npm

   npm install @lwc-garden/core tsx

   Optionally with @lwc-garden/utils

   npm install @lwc-garden/core @lwc-garden/utils tsx

   yarn

   yarn add @lwc-garden/core tsx

   Optionally with @lwc-garden/utils

   yarn add @lwc-garden/core @lwc-garden/utils tsx

2. Create a garden.config.ts file

   import { GardenConfig } from '@lwc-garden/core/types'
   import lwrConfig from './lwr.config.json' with { type: 'json' }
   
   export default {
     // lwc.config.json modules type
     modules: [...lwrConfig.lwc.modules],
   } satisfies GardenConfig

   You may also choose to use a vanilla JavaScript config file, garden.config.js, but it is highly recommended to use TypeScript for proper config typing support. Here is an example of a basic JavaScript config setup:

   import lwrConfig from './lwr.config.json' with { type: 'json' }
   
   /**
    * @type {import('@lwc-garden/core/types').GardenConfig}
    */
   const CONFIG = {
     // lwc.config.json modules type
     modules: [...lwrConfig.lwc.modules],
   }
   
   export default CONFIG

   This is the bare minimum configuration required to get LWC Garden working. This imports your module configuration from your existing lwc.config.json file.

   Don’t forget to add the garden config to your lwr.config.json file:

   lwr.config.json

   {
     "lwc": {
       "modules": [
         {
           "dir": "./.garden/components",
           "namespace": "garden"
         },
         {
           "dir": "./force-app/main/default/lwc",
           "namespace": "c"
         }
       ]
     },
     "moduleProviders": [
       "@lwrjs/label-module-provider",
       "@lwrjs/app-service/moduleProvider",
       "@lukethacoder/lwrjs-lwc-module-provider",
       "@lwrjs/npm-module-provider"
     ],
     "routes": [
       {
         "id": "app",
         "path": "/",
         "rootComponent": "garden/app",
         "layoutTemplate": "./.garden/layouts/index.html",
         "bootstrap": {
           "syntheticShadow": true
         }
       }
     ]
   }

3. Run the local dev server

   When working locally, the development server lets you preview your work and automatically refreshes your browser when you make changes.

   Run the following from the root of your SFDX Project:

   npx @lwc-garden/core dev

   This will log a message to your terminal with the URL of your local preview. Open this URL to start browsing your LWCs.