Migration info v3 to none

lwc-services

Because lwc-services is deprecated, if you want to migrate away from it, there are some configuration changes you will need to make.

First, make sure you are running lwc-services v3. If you are on v1 or v2, follow the other migration guides to update.

Because lwc-services is effectively a thin wrapper around Webpack/Rollup and Jest, the goal at the end of the migration is to use pure Webpack/Rollup and pure Jest.

lwc-services test:unit

This command is a thin wrapper around Jest and @lwc/jest-preset. You should be able to run:

npm install --save-dev jest@^26 @lwc/jest-preset@^11

Then, you will need to modify jest.config.js as described in the @lwc/jest-preset documentation.

Most likely, you will need to remove references to lwc-services from jest.config.js, and add something like:

// jest.config.js
module.exports = {
  preset: '@lwc/jest-preset',
  moduleNameMapper: {
    '^(my-namespace)/(.+)$': '<rootDir>/path/to/my/modules/$1/$2/$2'
  },
  /* ... */
}

And then instead of lwc-services test:unit, use:

jest

If your Jest config file is not jest.config.js, then you will need to run jest --config ./path/to/jest.config.js.

lwc-services build and lwc-services watch

This part of the guide assumes you are using Webpack. If you're using Rollup, refer to the official LWC Rollup documentation.

These commands can be replaced with Webpack itself. To do so, there is a bit of configuration required.

Install Webpack dependencies

First, install the necessary dependencies:

npm install --save-dev \
  copy-webpack-plugin@^5 \
  error-overlay-webpack-plugin@^1 \
  html-webpack-plugin@^5 \
  lwc-webpack-plugin@^2 \
  webpack@^5 \
  webpack-cli@^3 \
  webpack-dev-server@^3

These dependencies will do for us what lwc-services used to do.

Modify Webpack config

Next, you'll need to modify your Webpack config to use these plugins. Below is a basic configuration:

// webpack.config.js

const HtmlWebpackPlugin = require('html-webpack-plugin');
const CopyWebpackPlugin = require('copy-webpack-plugin');
const ErrorOverlayPlugin = require('error-overlay-webpack-plugin');
const LwcWebpackPlugin = require('lwc-webpack-plugin');
const path = require('path');

const mode = process.env.NODE_ENV || 'production';

module.exports = {
  entry: [
    path.join(__dirname, './src/client/index.js')
  ],
  mode,
  devtool: mode === 'development' && 'source-map',
  output: {
    path: path.join(__dirname, './dist'),
    filename: 'app.js',
    publicPath: '/'
  },
  plugins: [
    new webpack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify(mode)
    }),
    new LwcWebpackPlugin(),
    new HtmlWebpackPlugin({
      template: path.join(__dirname, './src/client/index.html')
    }),
    new CopyWebpackPlugin([
      // Copy from `resources` in `lwc-services.config.js`
      // See below for details.
    ])
  ]
};

Note that the entry point (here src/client/index.js) and template file (here src/client/index.html) will vary depending on the structure of your app.

Move resources to CopyWebpackPlugin

For the CopyWebpackPlugin, you will need to copy over the from/to files previously defined in lwc-services.config.js using the resources option. For instance, if you have:

// lwc-services.config.js
module.exports = {
  // ...
  resources: [
    {
      from: 'src/foo/bar',
      to: 'dist'
    },
    {
      from: 'src/baz/quux',
      to: 'dist'
    }
  ]
};

Then you should move this into webpack.config.js as:

// webpack.config.js
module.exports = {
  // ...
  plugins: [
    // ...
    new CopyWebpackPlugin([
      {
        from: path.join(__dirname, 'src/foo/bar'),
        to: path.join(__dirname, 'dist')
      },
      {
        from: path.join(__dirname, 'src/baz/quux'),
        to: path.join(__dirname, 'dist')
      }
    ])
  ]
};

Note the path.join(__dirname, ...), which creates an absolute file path relative to the location of the webpack.config.js file. It's assumed that webpack.config.js is located in the root of your project.

Not every Webpack configuration/plugin requires an absolute path, but many of them do (e.g. output.path). In other cases, relative paths may be ambiguous (e.g. CopyWebpackPlugin may copy into ./dist/dist instead of ./dist). So it's best to be explicit everywhere.

Copy config from lwc-services.config.js

Here is a full list of the available options in lwc-services.config.js and how to migrate them:

• buildDir – default directory for the build output
  • Equivalent to Webpack output.path
• bundler – bundler to use (Webpack or Rollup)
  • This guide assumes you are using Webpack. For Rollup, see lwc-barebone for a sample LWC+Rollup app.
• noclear – clears the build directory on every build
  • You can run rm -fr dist/ (or the name of your build directory) to achieve this
• sourceDir – default directory for source files
  • Equivalent to Webpack's entry
• resources – list of resources to copy to the build folder
  • See above notes on CopyWebpackPlugin
• devServer – default server options for watch command
  • Copy wholesale into webpack.config.js. Equivalent to Webpack's devServer.
• lwcCompilerOutput – LWC compiler options for production mode
  • Pass into the LwcWebpackPlugin as outputConfig (see below)
• lwcCompilerStylesheetConfig – LWC compiler options for the stylesheet config
  • Pass into the LwcWebpackPlugin as stylesheetConfig (see below)
• lwcExperimentalDynamicComponent – LWC compiler options for experimental dynamic components
  • Pass into the LwcWebpackPlugin as experimentalDynamicComponent (see below)

For the LwcWebpackPlugin, here is a sample usage showing how to pass in options:

// webpack.config.js
module.exports = {
  // ...
  plugins: [
    // ...
    new LwcWebpackPlugin({
      stylesheetConfig: { /* ... */ },
      outputConfig: { /* ... */ },
      experimentalDynamicComponent: { /* ... */ }
    })
  ]
};

Babel and TypeScript

If you need Babel to compile modern JavaScript into older JavaScript for legacy browsers, use the babel-loader plugin.

If you need TypeScript to compile TypeScript into JavaScript, then you can either use the babel-loader with @babel/preset-typescript or the ts-loader.

Run Webpack

Once you have Webpack installed and configured, you can run it.

Instead of lwc-services build, run:

NODE_ENV=production webpack

And instead of lwc-services watch, run:

NODE_ENV=development webpack-dev-server

If your Webpack config file is not webpack.config.js, then you will need to run these commands with --config ./path/to/webpack.config.js.

rollup-plugin-lwc-typescript

If you are using this project, you can switch to a solution using @babel/core and @babel/plugin-transform-typescript. See the source code for details.