@build-in-blocks/dev.build

Built with: Node.js v24.0.2

Supported Node.js versions: Node.js v20.x, v22.x, v24.x and v25.x

Overview: Production and development bundler build setup for your typescript web-related projects.

Description: Build production-ready typescript web apps (or web-based libraries) without your regular javascript/typescript web frameworks, with ease and speed. The @build-in-blocks/dev.build package contains preconfigured webpack setup for both development and production environment. After installation in your web project (and with very minimal intervention on your end), you just need to run npm run dev to generate a development mode bundle or npm run build to generate a well optimized production mode bundle.

User guide: See docs.users README.md

Contributor guide: See docs.contributors README.md

Run into any issues? Report them via our product issue reports repo

Quick installation & usage guide

[!NOTE]
Also see user guide 👆🏽 for more detailed guide on what's included in this package (out of the box) and customization.

1. Main package installation

• Install our dev build package as a devDependency in your project:

  npm install -D @build-in-blocks/dev.build --save-exact

• Also make sure to install the resources package, as this will be useful later (also so that your web app code can compile successfully without errors):

  npm install -D @build-in-blocks/dev.resources --save-exact

2. Typescript config setup

• You DON'T need to install typescript into your web project (this library already does that internally, relative to your web project). See typescript table in the general guide for more information: Typescript compatibility and usage.

• Just create a tsconfig.json file at the root of your web project, and add these:

  {
    "extends": "@build-in-blocks/dev.build/tsconfig.base.json",
    "compilerOptions": {
      "rootDir": "./src",
      "outDir": "./build",
      "declarationDir": "./build",
      "checkJs": false,
      "skipLibCheck": true,
    },
    "include": ["src"],
  }

3. Update your project's package.json

• Add dev and build scripts: In your web project's package.json file, add the dev and build scripts.

  • For macOS and linux, use:

    "scripts": {
      "dev": "blocks.pkg.dev.build dev:build",
      "build": "blocks.pkg.dev.build prod:build"
      // your other npm scripts in your project goes here as usual
    },

  • For windows OS, use:

    "scripts": {
      "dev": "blocks.pkg.dev.build.cmd dev:build",
      "build": "blocks.pkg.dev.build.cmd prod:build"
      // your other npm scripts in your project goes here as usual
    },

• You need this too: Add these in the your web project's package.json file too:

  {
    "type": "module",
    "sideEffects": false,
    // your other package.json property values go here as usual
  }

  [!NOTE]
  You need "type": "module" since this library package is ESM-first. sideEffects helps with treeshaking.

4. Source code folder and entry file for webpack

• Option 1 - Default webpack entry file path: If you create or use a src/index.ts file in your web project, the library will assume that you don't wish to change your webpack entry file path and want to stick to the default.

• option 2 - Override the default with your preferred entry file path: If you prefer e.g. app/main.ts to be your project's webpack entry file path, create a blocks.config.ts file at the root of your web project and add this code in there:

  import { BlocksConfig } from '@build-in-blocks/dev.resources';
  
  const blocksConfig: BlocksConfig = {
    devBuild: {
      srcCodeFolder: 'app',
      entryFileName: 'main',
    },
  };
  
  export default blocksConfig;

  [!NOTE]
  You'll also need to update your web project's tsconfig.json file's include array and rootDir i.e. change "src" to "app".

5. (Optional) index.html - run code in browser

If you plan to run your web project in the browser, add a main index.html file at the root of your source code folder i.e. it's file path should be src/index.html if you are using default, or e.g. app/index.html if you've used blocks config to override the default.

[!NOTE]
This will automatically include the main index.html file in the generated dist and build folders. Your entry point file is also injected in the generated index.html's body tag.

6. Run the npm scripts to generate output folders

• Local development build: Webpack will now watch your source code folder as you make changes to its content, and will also generate/update the dist output folder, when you run the dev script command:

  npm run dev

• Production build: Run the build script command, anytime you need to generate/update your production build i.e. the build output folder:

  npm run build

Contributors

Thanks to these amazing contributors to the @build-in-blocks/dev.build project. This project follows the all-contributors specification. See emoji key. Contributions of any kind welcome!