@jsenv/bundling/readme.md

# jsenv bundling

[![npm package](https://img.shields.io/npm/v/@jsenv/bundling.svg)](https://www.npmjs.com/package/@jsenv/bundling)
[![build](https://travis-ci.com/jsenv/jsenv-bundling.svg?branch=master)](http://travis-ci.com/jsenv/jsenv-bundling)
[![codecov](https://codecov.io/gh/jsenv/jsenv-bundling/branch/master/graph/badge.svg)](https://codecov.io/gh/jsenv/jsenv-bundling)

## Introduction

`@jsenv/bundling` is used by jsenv projects to generate files published on npm.<br />

It has the following exports

- `generateGlobalBundle`
- `generateCommonJsBundle`
- `generateSystemJsBundle`

## How to use

To understand how to use jsenv bundling let's use it on a "real" project.<br />
We will setup a basic project and generate different bundle formats.

### Basic project setup

1. Create basic project file structure

   — see [./docs/basic-project](./docs/basic-project)

2. Install dependencies

   ```console
   npm install
   ```

## `generateGlobalBundle` example

```console
node ./generate-global-bundle.js
```

Once done, terminal will contain a log with the path to the generated bundle.

— see [./docs/basic-project/dist/global/main.js](./docs/basic-project/dist/global/main.js)

## `generateCommonJsBundle` example

```console
node ./generate-commonjs-bundle.js
```

Once done, terminal will contain a log with the path to the generated bundle.<br />

— see [./docs/basic-project/dist/commonjs/main.js](./docs/basic-project/dist/commonjs/main.js)

## `generateSystemJsBundle` example

```console
node ./generate-systemjs-bundle.js
```

Once done, terminal will contain a log with the path to the generated bundle.<br />

— see [./docs/basic-project/dist/systemjs/main.js](./docs/basic-project/dist/systemjs/main.js)

## Bundling functions documentation

If you want to know more about these functions, there is a dedicated page for that.<br />
— see [bundling functions documentation](./docs/bundling-doc.md)

## Supported codebase

jsenv bundling can work with syntax like `top level await`.<br />
However some syntax are compatible only with a subset of the available bundle formats.<br />
For instance `generateCommonJsBundle` throw an error if it encounters a `top level await` in your codebase.<br />

You can find below some code examples and the associated bundle format compatibility.

### top level `await`

```js
const answer = await Promise.resolve(42)
```

Compatibility: ~~`global`~~, ~~`commonjs`~~, `systemjs`.

### dynamic `import`

```js
import("./file.js").then((namespace) => {
  console.log(namespace)
})
```

Compatibility: ~~`global`~~, `commonjs`, `systemjs`.

### `import.meta.url`

```js
const whereAMI = import.meta.url
```

Compatibility: `global`, `commonjs`, `systemjs`.

### `import.meta.resolve`

```js
import.meta.resolve("./file.js")

const lodashHref = import.meta.resolve("lodash")
// importMap are applied so that lodashHref might be /node_modules/lodash/index.js
```

Compatibility: `global`, `commonjs`.

### leading slash import

```js
import "/src/file.js"
// search file at "/Users/you/folder/src/file.js"
```

Compatibility: `global`, `commonjs`, `systemjs`.

### import remapping

```js
import memoize from "lodash"
// search file at "/node_modules/lodash/index.js"
```

Compatibility: `global`, `commonjs`, `systemjs`.

### json

```js
import data from "./data.json"
```

Compatibility: `global`, `commonjs`, `systemjs`.

### globalThis

```js
globalThis.console.log("Hello")
```

Compatibility: `global`, `commonjs`, `systemjs`.

## Installation

```console
npm install --save-dev @jsenv/bundling@5.7.0
```

```console
yarn add @jsenv/bundling@5.7.0 --dev
```