How to use

Tooling requirements

The basic use requirements:

NodeJS version 18+
NPM

There appear to be dependency mapping issues with Yarn v1.x.x lock files, Typescript and webpack, and specific dependencies using ES modules. If you do decide to use Yarn use the latest version.

Set up a project

weldable makes assumptions on project structure in order to be up and moving. Many of these assumptions can be overridden, or ignored, to fit your own preferences.

Assumptions weldable presets...

src project directory, Your project -> src -> your work
index.(js|mjs|cjs|jsx|ts|mts|cts|tsx) application prefix and possible extensions located in src, Your project -> src -> index.(js|mjs|cjs|jsx|ts|mts|cts|tsx)
dist directory for webpack bundle output, Your project -> dist
localhost host name
port default of 3000

To alter these presets see dotenv use.

Basic setup

All setup directions are based on a MacOS experience. If Linux, or Windows, is used and you feel the directions could be updated please open a pull request to update documentation.

For those with experience, to get up and running quickly...

Confirm you installed the correct version of NodeJS
Confirm you added weldable as a dependency to your project
Make sure you have a src directory with at least an index.(js|ts)

Create NPM scripts that reference the weldable CLI

"scripts": {
 "build": "weldable",
 "start": "weldable -e development"
},

Run the NPM scripts and that's it, customize away!

And for those with less experience, directions for all...

Confirm you installed the correct version of NodeJS. The current minimum NodeJS version is noted on the main README.md
Create a new directory, open your terminal and change directories into it
```
$ cd ./[new_directory]
```
Create your package.json file. You can use the terminal to initialize the project, you'll be asked questions (there are defaults, just hit enter or fill them out)...
```
$ npm init
```
After creating package.json. Add weldable as a devDependency via the terminal
```
$ npm i weldable --save-dev
```
Next, add a src directory to your new directory, like new_directory -> src
Next, add an index.js file to src, like new_directory -> src -> index.js

Add the following contents to index.js

const body = document.querySelector('BODY');
const div = document.createElement('div');
div.innerText = `hello world`;
body.appendChild(div);

To get everything running, we need to add some NPM scripts inside the package.json scripts section
```
"scripts": {
 "build": "weldable",
 "start": "weldable -e development"
},
```
Next, in the terminal, lets run the development mode.
```
$ npm start
```
If everything is working correctly you should see messaging telling you where files are running.

If everything did NOT work, you may receive messaging from weldable, or webpack, explaining what the issue is. If you receive no error messaging a standard practice is to reconfirm you have the correct tooling installed and walk back through the previous steps.
Finally, in the terminal, we'll create our bundle
```
$ npm run build
```
If everything is working correctly you should see messaging telling you basic bundle stats and a successful completion message. You can access your bundle under the dist directory.

If things are NOT working, weldable and webpack should provide messaging to help you debug why your bundle isn't being compiled

Set up a JS framework, like React

At its most basic weldable does not work out of the box with frameworks, like React, unless a loader we've included happens to support said framework, such as ts-loader and React.

What that means is you may have to modify and use your own webpack configuration loader.

Set up a React project with ts-loader

Confirm you installed the correct version of NodeJS
Confirm you added weldable as a dependency to your project
Confirm you added react and react-dom as dependencies for your project

Create a basic tsconfig.json in the root of your project directory with the following content. After everything is working modify as needed.

  {
    "compilerOptions": {
      "allowJs": true,
      "allowSyntheticDefaultImports": true,
      "jsx": "react",
      "module": "esnext",
      "moduleResolution": "node"
    }
  }

Make sure you have a src directory with at least an index.tsx, and the following content.

  import React from 'react';
  import { createRoot } from 'react-dom/client';

  const body = document.querySelector('BODY');
  const div = document.createElement('div');
  body?.appendChild(div);

  const App = () => <>hello world</>; 

  const root = createRoot(div);
  root.render(<App />);

Create NPM scripts that reference the weldable CLI

  "scripts": {
   "build": "weldable -l ts",
   "start": "weldable -e development -l ts"
  }

Run the NPM scripts and that's it. You should see hello world, when you run $ npm start, displayed in a browser window.

If the browser failed to open you can find the content at http://localhost:3000/

Set up a React project with babel-loader

Confirm you installed the correct version of NodeJS
Confirm you added weldable as a dependency to your project
Confirm you added react and react-dom as dependencies for your project
Create a basic babel.config.js file with the following content
```
  module.exports = {};
```

Create a basic webpack.config.js in the root of your project directory with the following content. After everything working modify as needed.

  const { babelLoaderResolve, babelPresetEnvResolve, babelPresetReactResolve } = require('weldable/lib/packages');

  module.exports = ({ SRC_DIR } = {}) => ({
    module: {
      rules: [
        {
          test: /\.(jsx|js)?$/,
          include: [SRC_DIR],
          use: [
            {
              loader: babelLoaderResolve,
              options: {
                presets: [babelPresetEnvResolve, babelPresetReactResolve]
              }
            }
          ]
        }
      ]
    }
  });

Make sure you have a src directory with at least an index.js, and the following content.

  import React from 'react';
  import { createRoot } from 'react-dom/client';

  const body = document.querySelector('BODY');
  const div = document.createElement('div');
  body?.appendChild(div);

  const App = () => <>hello world</>; 

  const root = createRoot(div);
  root.render(<App />);

Create NPM scripts that reference the weldable CLI

  "scripts": {
   "build": "weldable -x ./webpack.config.js",
   "start": "weldable -e development -x ./webpack.config.js"
  }

Run the NPM scripts and that's it. You should see hello world, when you run $ npm start, displayed in a browser window.

If the browser failed to open you can find the content at http://localhost:3000/

dotenv use

weldable makes use of dotenv parameters for aspects of webpack configuration overrides.

Instead of dotenv files you can choose to export parameters via the terminal

dotenv via terminal

Using the terminal to handle dotenv parameters Set a parameter

export YOUR_DOTENV_PARAM="lorem ipsum"; echo $YOUR_DOTENV_PARAM

Unset a parameter

unset YOUR_DOTENV_PARAM; echo $YOUR_DOTENV_PARAM

dotenv via files

dotenv files are structured to cascade, similar to stylesheets. Each additional dotenv file builds settings from a root .env file.

 .env = base dotenv file settings
 .env.local = local settings overrides that enhance the base .env settings
 .env -> .env.development = development settings that enhances the base .env settings
 .env -> .env.development.local = local run development settings that enhances the base .env and .env.development settings
 .env -> .env.production = build modifications associated with all environments
 .env -> .env.production.local = local run build modifications that enhance the base .env and .env.production settings

In certain instances it is encouraged that you .gitignore all dotenv files since they can contain application settings. For this framework, however, we encourage application settings being applied to .env*.local files and adding 2 entries to your project's .gitignore

!.env
.env*.local

This allows you to have both local settings that are NOT checked in, and settings that are.

Available dotenv parameters

weldable makes use of exposed dotenv parameters to handle webpack configuration settings...

dotenv parameter	definition	default value
RELATIVE_DIRNAME (read only)	A dynamically build populated string reference for the root context path
APP_INDEX_PREFIX	A static string for the webpack application entry file `[APP_INDEX_PREFIX].[ext]`	index
DIST_DIR	A static string for the webpack build output directory	./dist
HOST	A static string for the webpack dev server host	localhost
HTML_INDEX_DIR	A static string referencing what directory your `index.html` file is located. If there is no `index.html`, webpack is nice, it'll create one for you.	./src
NODE_ENV
PORT	A static number for the webpack dev server port	3000
OPEN_PATH	A static string for the webpack dev server browser open path
PUBLIC_PATH	A static string for the webpack output base expected path of your application. Tip: This parameter can cause `webpack` to reference an incorrect path, specifically for static assets and your bundle output, resulting in `404`s and hair-pulling during development, see `webpack` docs for more info	/
PUBLIC_URL	A static string alias for PUBLIC_PATH	/
SRC_DIR	A static string for application source directory	./src
STATIC_DIR	A static string associated with the directory containing static build assets. We've generally used this directory for files included directly in `index.html`, and resources included with XHR. Warning: importing, or requiring, assets from this directory to within the `SRC_DIR` WILL cause webpack to attempt bundling the asset along with copying it!
UI_NAME	A static string title for `index.html`. `index.html` being a file you, or webpack, creates within the STATIC_DIR

Technically all dotenv parameters are strings. When consuming them it is important to cast them accordingly.

CLI use

Basic CLI functionality can also be viewed under a simple terminal command

$ weldable -h

Options

CLI OPTION	DESCRIPTION	TYPE	CHOICES	DEFAULT
-e, --env	Use a default configuration type if NODE_ENV is not set to the available choices of "development" and "production"	string	development, production	production
-l, --loader	Preprocess loader, use the classic JS (babel-loader), TS (ts-loader), or "none" to use webpack defaults, or a different loader.	string	js, ts, none	js
-s, --stats	Stats output level for NodeJS API	string	errors-only, errors-warnings, minimal, none, normal, verbose, detailed, summary	normal
--standalone	Standalone webpack configuration. Output weldable webpack config functions and update package.json so you can do whatever you want.	boolean
--statsFile	Output JSON webpack bundle stats for use with "webpack-bundle-analyzer". Use the default or enter a relative path and filename	string		./stats.json
--tsconfig	Generate a base tsconfig from one of the available NPM @tsconfig/[base]. An existing tsconfig.json will override this option, see "tsconfig-opt". This option can be run without running webpack.	string	create-react-app, node18, node20, react-native, recommended, strictest
--tsconfig-opt	Regenerate or merge a tsconfig. Useful if a tsconfig already exists. Requires the use of "tsconfig" option	string	merge, regen	regen
-x, --extend	Extend, or override, the default configs with your own relative path webpack configs using webpack merge. Configuration can be a callback that returns a webpack config object, available dotenv parameters are returned as the callback parameter.	string \| Array<string>
-h, --help		boolean
-v, --version		boolean

Use the CLI with NPM scripts

CLI usage can be placed under NPM scripts

A basic development start, and production build, using your own scripts

"scripts": {
  "start": "weldable -e development",
  "build": "weldable"
}

A development start, and production build, using your own webpack configurations merged with the defaults.

"scripts": {
  "start": "weldable -e development -x ./webpack.yourCustomBuild.js -x ./webpack.developmentBuild.js",
  "build": "weldable -x ./webpack.yourCustomBuild.js -x ./webpack.productionBuild.js"
}

Use weldable to generate a webpack configuration

You can output the weldable webpack and support configuration files, plus the associated NPM packages and scripts into an existing or new project. These resources are current to any modifications made to weldable itself.

You'll need to have weldable installed, locally, globally or use npx. Similar to Create React Apps ability of generating and "ejecting", but without the doom and gloom. You can always go back to weldable.

To get the output...

Run the --standalone option.

$ cd [into a directory to generate the configuration in]
$ npx weldable --standalone

And that's it. You should now have a basic webpack configuration setup. If this is a new project you should be able to immediately use the new NPM scripts like $ npm run standalone:start.

Files that are created, or modified, generally vary when the --loader option is used, for example: $ npx weldable --standalone --loader=ts

Changes include...

A webpack.config.js file is created
A modified, or basic, package.json is created
- 2 NPM scripts should be added, both are prefixed with standalone:
  - standalone:build
  - standalone:start
- multiple developer dependencies should be added
A basic hello world ./src/index.[js|ts] file is created, if none exists
Additional configuration may also be generated. Console output should provide a listing of all skipped, modified, and added files.

After everything is generated feel free to move and modify the files as needed since you'll no longer need weldable.

Lib use

The lib aspect of weldable is exported as CommonJS and is intended to be run as part of your build process without the need to install many additional packages.

Two primary things are exposed through weldable...

packages, such as webpack-merge
and weldable "helper" functions

Example use within build files...

const { dotenv } = require('weldable');

const dotenvFunc = dotenv.[FUNC];

Exposed packages

See our package.json dependencies for exposed packages.

You can also use the weldable namespace, or you can always call the package directly...

const packages = require('weldable/lib/packages');

const aPackage = packages.[PACKAGE_NAME];

Heads up

Packages is kept separated from weldable functions due to ES module loading. Certain packages do but others don't provide modules which can cause issues with tooling, such as Jest.
Every package has 2 exported aspects, the required package and a require.resolve
We do not provide package use documentation. For package use review associated package.
All packages retain their respective license. It is your responsibility to use said packages accordingly.

The weldable lib bundles a txt resource containing available license materials.

PACKAGES	EXPOSED NAME
@babel/core	babelCore, babelCoreResolve
@babel/plugin-transform-runtime	babelPluginTransformRuntime, babelPluginTransformRuntimeResolve
@babel/preset-env	babelPresetEnv, babelPresetEnvResolve
@babel/preset-react	babelPresetReact, babelPresetReactResolve
@tsconfig/create-react-app	N/A
@tsconfig/node18	N/A
@tsconfig/node20	N/A
@tsconfig/react-native	N/A
@tsconfig/recommended	N/A
@tsconfig/strictest	N/A
babel-loader	babelLoader, babelLoaderResolve
copy-webpack-plugin	CopyWebpackPlugin, CopyWebpackPluginResolve
css-loader	cssLoader, cssLoaderResolve
css-minimizer-webpack-plugin	CssMinimizerWebpackPlugin, CssMinimizerWebpackPluginResolve
dotenv	dotenv, dotenvResolve
dotenv-expand	dotenvExpand, dotenvExpandResolve
dotenv-webpack	dotenvWebpack, dotenvWebpackResolve
eslint-webpack-plugin	EslintWebpackPlugin, EslintWebpackPluginResolve
html-replace-webpack-plugin	htmlReplaceWebpackPlugin, htmlReplaceWebpackPluginResolve
html-webpack-plugin	HtmlWebpackPlugin, HtmlWebpackPluginResolve
less	less, lessResolve
less-loader	lessLoader, lessLoaderResolve
mini-css-extract-plugin	MiniCssExtractPlugin, MiniCssExtractPluginResolve
mini-svg-data-uri	miniSvgDataUri, miniSvgDataUriResolve
rimraf	rimraf, rimrafResolve
sass	sass, sassResolve
sass-loader	sassLoader, sassLoaderResolve
style-loader	styleLoader, styleLoaderResolve
terser-webpack-plugin	TerserWebpackPlugin, TerserWebpackPluginResolve
ts-loader	tsLoader, tsLoaderResolve
tsconfig-paths-webpack-plugin	tsconfigPathsWebpackPlugin, tsconfigPathsWebpackPluginResolve
tslib	tslib, tslibResolve
typescript	typescript, typescriptResolve
webpack	webpack, webpackResolve
webpack-bundle-analyzer	webpackBundleAnalyzer, webpackBundleAnalyzerResolve
webpack-cli	WebpackCli, WebpackCliResolve
webpack-dev-server	WebpackDevServer, WebpackDevServerResolve
webpack-merge	webpackMerge, webpackMergeResolve

An example webpack config rules loader using the provided require.resolve...

const { cssLoaderResolve, MiniCssExtractPlugin, sassLoaderResolve } = require('weldable/lib/packages');

module.exports = ({ SRC_DIR } = {}) => ({
  module: {
    rules: [
      {
        test: /\.(sa|sc)ss$/i,
        use: [MiniCssExtractPlugin.loader, cssLoaderResolve, sassLoaderResolve]
      }
    ]
  }
});

Exposed weldable functions

weldable exposes limited helper functions

You can access the functions like so...

const { dotenv } = require('weldable');

const dotenvFunc = dotenv.[FUNC];

HELPER	EXPOSED NAME	DESCRIPTION
dotenv	dotenv	An object group of helper functions designed to consume dotenv files. Useful for implementing your own dotenv parameters used during testing, or for a standalone webpack build
dotenv.setupDotenvFilesForEnv	dotenv.setupDotenvFilesForEnv	A function for use with non-webpack configurations. Access local and specific dotenv file parameters. Failed or missing parameters return an empty string.
dotenv.setupWebpackDotenvFilesForEnv	dotenv.setupWebpackDotenvFilesForEnv	A function for use with webpack configurations. Set multiple webpack dotenv file parameters during configuration and build.

Examples

Example usage with Jest, setupTests.js. This will allow the use of .env.test and .env.test.local files.

/**
 * Set dotenv params for use during testing.
 */
setupDotenvFilesForEnv({ env: 'test' });

Example usage with a webpack build configuration. The associated dotenv files would be

.env
.env.local
.env.loremIpsum
.env.loremIpsum.local

const { dotenv } = require('weldable');
const { setupDotenvFilesForEnv, setupWebpackDotenvFilesForEnv } = dotenv;

process.env.NODE_ENV='development';

const {
  RELATIVE_DIRNAME,
  DIST_DIR
  HOST
  NODE_ENV
  PORT
  OPEN_PATH
  PUBLIC_PATH
  PUBLIC_URL
  SRC_DIR
  STATIC_DIR
} = setupDotenvFilesForEnv({
  env: 'loremIpsum',
  relativePath: process.cwd()
});

const webpackProduction = {
...
  plugins: [
    ...setupWebpackDotenvFilesForEnv({
      directory: RELATIVE_DIRNAME,
      env: NODE_ENV
    }),
...
};

setupDotenvFilesForEnv falls back to creating a NODE_ENV parameter if one is not already set. It is recommended if you decide to use webpack and a non-standard env beyond development or production you also export a NODE_ENV=development or NODE_ENV=production to avoid issues.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCS.md

DOCS.md

How to use

Tooling requirements

Set up a project

Basic setup

Set up a JS framework, like React

dotenv use

dotenv via terminal

dotenv via files

CLI use

Options

Use the CLI with NPM scripts

Use weldable to generate a webpack configuration

Lib use

Exposed packages

Exposed weldable functions

Files

DOCS.md

Latest commit

History

DOCS.md

File metadata and controls

How to use

Tooling requirements

Set up a project

Basic setup

Set up a JS framework, like React

dotenv use

dotenv via terminal

dotenv via files

CLI use

Options

Use the CLI with NPM scripts

Use weldable to generate a webpack configuration

Lib use

Exposed packages

Exposed weldable functions