p-element-build

P-BUILD

Scripts for building and testing web components

The scripts uses:

• [esbuild]@(https://esbuild.github.io/) for transpiling and bundeling typescript to javascript
• typescript for generating typings
• postcss for css pre processing
• jasmine Browser test runner
• playwright Test framework
• express local development web server

And provides the config for eslint

• eslint linting
• prettier code formatter (eslint plugin)
• sonarjs typescript analyzer (eslint plugin)

Getting Started

Add p-element-build to your project

npm i p-element-build

Create a src folder and add a source file eg my-component.tsx

Create test code in src/my-component.spec.tsx

Create p-build.json in the root of your project

{
    "entryPoints": [
      "./src/my-component.tsx"
    ],
    "testEntryPoints": [
      "./src/my-component.spec.tsx"
    ],
    "entryNames": "[name]",
    "devServer" : {
      "port": 9000,
      "host": "localhost"
    },
    "dist": "./dist",
    "target": "es6",
    "testFiles": [],
    "browsers": ["chromium", "firefox", "webkit"],
    "chromiumPath": "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"
  }

format

Configure the format (optional) could be iife, cjs or esm

"format": "esm"

external

You can mark a file or a package as external to exclude it from your build. (optional)

"external": ["react", "react-dom"]

Add scripts to the package.json

 ...
  scripts{
    "build": "p-build --action build",
    "develop": "p-build --action develop",
    "test": "p-build --action test",
    "testdevelop": "p-build --action testdevelop"
    ...
  }
  ...

nodeModulesPath

If your project is part of a workspace you need to configure the (relative) path to the node_modules.

"nodeModulesPath": "../../node_modules",

p-build actions

Action develop

p-build --action develop

The develop action starts a dev server (express), transpiles and bundles each configured entry point defined in p-build.json to the configured dist folder.
The javascript is not minified and contains inline source maps.

  {
    "entryPoints" : ["./src/my-component.tsx"],
    ...
    "dist": "./dist",
  }

Css files defined in p-build.json will be pre-process with postcss and saved to in the dist folder.

  {
    "cssFiles" : [
      {
        "src": "src/my-main.css",
        "target": "my-main.css"
      }
    ]
  }

The css is not minified.

Dev server config

{
  ...
  "devServer" : {
    "port": 9000,
    "host": "localhost",
    "api": "./api/example.mjs"
  },
  ...
}

If no host is configured all available network interfaces are used

You can add your api middleware

./api/example.mjs

const api = (app) => {

  app.get("/api/greet", (req, res) => {
    res.send({message: "hi"});
  });
}

export default api;

Action build

p-build --action build

entryNames

The entryNames option determines the naming scheme for the output files. This option accepts a template string that contains special placeholders. These placeholders are replaced with real values during the build process. For example, if you choose "[name]" only the files will be build in the /dist folder without the projects subfolders.

Here are the placeholders you can use in the entryNames option::

• [dir]: The directory of the input file, relative to the base of the input folder.
• [name]: The base name of the input file, without the directory or extension.
• [ext]: The extension of the input file, including the dot (e.g., .js).
• [hash]: A hash of the file's content. You can specify the length of the hash by adding a number, for example, [hash:8] for an 8-character long hash.

 {
  ...
    "entryNames": "[dir]/[name]",
  ...
 }
  

Build action tasks:

• delete the dist and types folder (if there is any)
• transpile, bundle and minify the entry points.
• preproces and minify css files
• generate typings (in types folder)

Action testdevelop

p-build --action testdevelop

The develop action starts a dev server (express), transpiles and bundles each configured test entry point defined in p-build.json to the configured dist folder.
The javascript is not minified and contains inline source maps.

All configured playwright browsers will be launched and the jasmine test page will be opend.

availiable browsers:

• chromium
• firefox
• webkit

You can override de chromium browsers, just add the path to the browser executable in the chromiumPath in p-build.json. Use C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe to launch the Edge browser on windows

You can define extra test files in p-build.json these files will be added to the jasmine test page. files with extension .js are added as script elements, .mjs as script elements with type="module" attribute and .css as link elements with the rel="stylesheet" attribute.

If you want to add a esm test file add a object with src and type.

  {
    ...
    "testFiles": [
      {
        "src": "node_modules/p-elements-core/dist/p-elements-core-modern.js}",
        "type": "module"
      },
      {
        "src": "dist/theme.css",
        "type": "stylesheet"
      },
      "node_modules/@pggm/common-form-components/dist/common-form-components.js",
      "dist/my-stylesheet.css"
    ],
    ...
  }

Action watch

p-build --action watch

Watch without starting a dev server

Action test

p-build --action test

Test file config

Array list of test files used as entry points for running tests and code coverage.

  {
    ...
    "testEntryPoints": [
          "./src/my-component.spec.tsx"
        ],
    ...
   }

Entries

testFileType config

Optional property to include multiple test file types other than the default .spec and .test

  {
    ...
    "testFileType": "__test__",
    ...
   }

Test action tasks:

• transpile, bundle and minify the test entry points.
• launch the first defined browser (make sure this is the chromium browser)
• open the jasmine test page
• execute the tests
• create TESTS-xunit.xml test report
• create html and cobertura coverage reports in coverage folder

.js, .ts, .tsx, .jsx, .mjs, .cjs and .esm files not containing .spec, .test or defined in testFileType, will be added to the coverage report. Files in the node_modules directory will be excluded.

You can override the default jasmine config by adding the config in the p-build.json

{
 ...
 "jasmineConfig": {
    "random": false
  },
  ...
}

Postcss config

Typescript imported css files and css files configured are the postcss pre-processor with these plugins:

• "postcss-preset-env"
• "postcss-import"
• "cssnano" **

** --action build only

override postcss

Configure your own plugins in a postcss.config.js file in project root folder

/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: [
    // ... your plugins
  ]
}

module.exports = config

ESlint config

Create eslint.config.mjs file in project root folder

import config from "@pggm/p-build/eslint.config.mjs";

export default config;

Boilerplate

$ git clone https://github.com/p-huisman/esbuild-p-element-boilerplate.git my-component

$ cd my-component

$ rm -rf ./.git