# @dtwo/module-builder

> Complete solution to build Dtwo Modules

Latest version **0.2.1** (published 2023-11-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install @dtwo/module-builder
pnpm add @dtwo/module-builder
yarn add @dtwo/module-builder
bun add @dtwo/module-builder
```

Provides the commands `dtwo-build-module`, `dtwo-module-build`.

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.1 |
| Published | 2023-11-20 |
| First published | 2023-11-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 5 |
| Unpacked size | 9.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | nkduy |

## Links

- npm: https://www.npmjs.com/package/@dtwo/module-builder
- npm.io page: https://npm.io/package/@dtwo/module-builder

## Dependencies (5)

- [mri](https://npm.io/package/mri.md) ^1.2.0
- [mlly](https://npm.io/package/mlly.md) ^1.0.0
- [pathe](https://npm.io/package/pathe.md) ^1.0.0
- [consola](https://npm.io/package/consola.md) ^2.15.3
- [unbuild](https://npm.io/package/unbuild.md) ^1.0.1

## Recent versions

- 0.2.1 (latest) — 2023-11-20

## README

# 📦 Dtwo Module Builder

> Complete solution to build Dtwo Modules.

## Features

- Compatible with Dtwo 3 and Dtwo Kit
- Automated build config using last module spec
- Typescript and ESM support
- Auto generated CommonJS stubs
- Auto generated types and shims for `@dtwo/schema`


## Learn More

### Requirements

For a user to use a module generated from module-builder, it's recommended they have:
- Node.js >= 14.x. _Latest Node LTS preferred_
- Dtwo 3 or Dtwo Bridge. _Dtwo 2 is functional but not advised_

## Quick start

You can quickly get started with the pre-configured [module starter](https://github.com/d2js/starter/tree/module):

```bash
$ npx @dtwo/cli init -t module my-module
```

## Project structure

### `src/module.ts`

This is the entrypoint for module definition.

A default export using `defineDtwoModule` and `ModuleOptions` type export is expected.

You could also optionally export `ModuleHooks` to annotate any custom hooks the module uses.

```ts [src/module.ts]
import { defineDtwoModule } from '@dtwo/kit'

export interface ModuleOptions {
  apiKey: string
}

export interface ModuleHooks {
  'my-module:init': any
}

export interface ModulePublicRuntimeConfig {
  NAME: string
}

export interface ModulePrivateRuntimeConfig {
  PRIVATE_NAME: string
}

export default defineDtwoModule<ModuleOptions>({
  meta: {
    name: 'my-module',
    configKey: 'myModule'
  },
  defaults: {
    apiKey: 'test'
  },
  async setup (moduleOptions, dtwo) {
    // Write module logic in setup function
  }
})
```

### `src/runtime/`

Any runtime file and code that we need to provide by module including plugins, composables and server api, should be in this directory.

Each file will be transformed individually using [unjs/mkdist](https://github.com/unjs/mkdist) to `dist/runtime/`.

<!-- TODO: Docs about how to address runtime from within setup -->

### `package.json`:

A minimum `package.json` should look like this:

```json [package.json]
{
  "name": "my-module",
  "license": "MIT",
  "version": "1.0.0",
  "exports": {
    ".": {
      "import": "./dist/module.mjs",
      "require": "./dist/module.cjs"
    }
  },
  "main": "./dist/module.cjs",
  "types": "./dist/types.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "prepack": "dtwo-module-build"
  },
  "dependencies": {
    "@dtwo/kit": "npm:@dtwo/kit-edge@latest"
  },
  "devDependencies": {
    "@dtwo/module-builder": "latest"
  }
}
```

## Dist files

Module builder generates dist files in `dist/` directory:

- `module.mjs`: Module entrypoint build from `src/module`
- `module.json`: Module meta extracted from `module.mjs` + `package.json`
- `module.cjs`: ESM proxy to allow require module in CommonJS context
- `types.d.ts`: Exported types in addition to shims for `dtwo.config` auto completion.
- `runtime/*`: Individually transformed files using [unjs/mkdist](https://github.com/unjs/mkdist)
  - Javascript and `.ts` files will be transformed to `.mjs` with extracted types on `.d.ts` file with same name
  - `.kdu` files will be transformed with extracted `.d.ts` file
  - Other files will be copied as is

## License

[MIT](./LICENSE)

---
_Source: https://npm.io/package/@dtwo/module-builder · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._