npm package: @hydroperx/webpack
Description: Web project development tool.
Author: Hydroper
Latest version: 1.0.9

# Webpack

An easier version of the [Webpack](https://webpack.js.org) development tool with built-in features:

- Project creation
- TypeScript
- JSON import (.JSON)
- Cascadings style sheet import (.CSS, .SASS, .SCSS)
- Media import such as `import _img_ef from "a.svg";`
- A world wide web root `/static` directory
- An optional .env file (`import.meta.env.X`)

Vantages over other bundlers:

- Support for the `browser` field in the NPM manifest

Minimal projects have only two direct development dependencies: `typescript` and `@hydroperx/webpack`.

## Installation

```sh
# global
npm i -g @hydroperx/webpack
# local
npm i @hydroperx/webpack
```

## Creating a project

Create a vanilla TypeScript web project:

```sh
webpack new --vanilla hello-world
```

Create a React + TypeScript web project:

```sh
webpack new --react hello-world
```

## Debugging a project

```sh
webpack run
# or
npm run dev
```

## Building a project

```sh
# debug build
webpack build
# release build
webpack build --release

# or
npm run build
npm run build -- --release
```

## Configuration

The configuration file `webpack.json` may be included in the project.

```json
{
    "entry": "./src/index.ts",
    "document": "./src/index.html"
}
```

**Supported options**

| Option               | Description           |
| -------------------- | --------------------- |
| **entry**            | The entry point program. (.ts, .tsx). Defaults to either `./src/index.tsx` or `./src/index.ts`. |
| **document**         | The entry point hypertext document (.html). Defaults to `./src/index.html` |

## Importing media

Allow importing media in your project by adding a `.d.ts` file declaring the file extension modules, such as:

**declaration.d.ts**

```ts
declare module "*.png";
```

`.png` files can then be imported as in:

```ts
import _png0 from "./example.png";
```

If the media is of small size, it is included directly as a base64 data URL.

**Supported file formats**

PNG/JPG/JPEG/GIF/SVG/WEBP/MP4/MP3/WOFF/WOFF2/EOT/TTF/OTF

## Accessing environment variables

Allow using environment variables from the project's `.env` file by adding a `.d.ts` file overriding the `ImportMeta` interface:

**env.d.ts**

```ts
interface ImportMetaEnv {
    readonly EXAMPLE: string;
}
  
interface ImportMeta {
    readonly env: ImportMetaEnv;
}
```

`import.meta.env.EXAMPLE` then refers to the `EXAMPLE` variable.

## The world wide web root

Insert public files into the web project's root by adding them to the `<project>/static` directory, which is the world wide web root.

For instance:

```
<project>/static/favicon.png
<project>/static/style.css
```

## Importing cascading style sheets

The following will import a cascading style sheet statically into the document:

```ts
import "./style.css";
```

**Supported file formats**

CSS/SASS/SCSS

## Importing JSON

The following will import a JSON file statically:

```ts
import data from "./data.json";
```

**Supported file formats**

JSON/GEOJSON

## Browser manifest field

The NPM manifest (`package.json`) may specify the [`browser` field](https://github.com/defunctzombie/package-browser-field-spec), commonly used for disabling certain Node.js specific modules and for replacing Node.js compatible sources by browser compatible sources (`.ts` extensions included).

**Manifest example**

```json
{
  "name": "hello-world",
  "version": "0.1.0",
  "browser": {
    "./src/module.nodejs.ts": "./src/module.web.ts"
  }
}
```