packages/preset-cjs/README.md
<div align="center">
🏄🏻 _A collection of opinionated configurations for a typescript project for presetter_
• [Quick Start](#quick-start) • [Project Structure](#project-structure) • [Customization](#customization) • [Scripts](#script-template-summary) •
[](https://github.com/alvis/presetter/releases)
[](https://github.com/alvis/presetter/actions)
[](https://codeclimate.com/github/alvis/presetter/maintainability)
[](https://codeclimate.com/github/alvis/presetter/test_coverage)
[](https://snyk.io/test/github/alvis/presetter?targetFile=packages/preset-esm/package.json&style=flat-square)
[](https://libraries.io/npm/presetter-preset-cjs)
[](https://github.com/alvis/presetter/blob/master/LICENSE)
</div>
**presetter-preset-cjs** is an opinionated extension of [**presetter-preset-esm**](https://github.com/alvis/presetter/tree/master/packages/preset-esm) but loaded with tools to help you to develop an common js application with ease. As the same as presetter-preset-esm, it's designed to help you get started with a typescript project in a fraction of time you usually take via [**presetter**](https://github.com/alvis/presetter).
With `presetter-preset-cjs`, it provides everything bundled from presetter-preset-esm, plus the ease of writing an commonjs application.
## Features
- 🔍 Searches and replaces `__dirname` and `__filename` refs with the `import.meta` equivalent
- 🥹 Forget about writing the [`.js`/`.ts` extension pain](https://github.com/microsoft/TypeScript/issues/37582) for each import
With this preset, estensions are automatically added post tsc. i.e. `import {foo} from './foo'` → `import {foo} from './foo.js'`
## Quick Start
To kick start a ESM application, what you need is to set the following in your `package.json` and follow the guide below.
```json
{
"type": "module",
"main": "lib/index.js",
"types": "lib/index.d.ts"
}
```
[**FULL DOCUMENTATION IS AVAILABLE HERE**](https://github.com/alvis/presetter/blob/master/README.md)
1. Bootstrap your project with presetter-preset-cjs
```shell
npx presetter use presetter-preset-cjs
```
That's. One command and you're set.
2. Develop and run life cycle scripts provided by the preset
At this point, all development packages specified in the preset are installed,
and now you can try to run some example life cycle scripts (e.g. run prepare).
## Project Structure
After installation, your project file structure should resemble the following or with more configuration files if you also installed other presets such as [`presetter-preset-rollup`](https://github.com/alvis/presetter/blob/master/packages/preset-rollup).
Implement your business logic under `source` and prepare tests under `spec`.
**TIPS** You can always change the source directory to other (e.g. src) by setting the `source` variable in `.presetterrc.json`. See the [customization](https://github.com/alvis/presetter/blob/master/packages/preset-esm#customization) section below for more details.
```
(root)
├─ .eslintrc.json
├─ .git
├─ .husky
├─ .jestrc.json
├─ .lintstagedrc.json
├─ .npmignore
├─ .prettierrc.json
├─ .presetterrc.json
├─ node_modules
├─ source
│ ├─ <folders>
│ ├─ index.ts
│ ├─ (auxiliary).ts
├─ spec
│ ├─ *.spec.ts
├─ package.json
├─ tsconfig.json
└─ tsconfig.build.json
```
## Customization
By default, this preset exports a handy configuration for rollup for a typescript project.
But you can further customize (either extending or replacing) the configuration by specifying the change in the config file (`.presetterrc` or `.presetterrc.json`).
These settings are available in the `config` field in the config file. For directories, the setting is specified in the `variable` field.
The structure of `.presetterrc` should follow the interface below:
```ts
interface PresetterRC {
/** name of the preset e.g. presetter-preset-cjs */
name: string | string[];
/** additional configuration passed to the preset for generating the configuration files */
config?: {
// ┌─ configuration for other tools via other presets (e.g. presetter-preset-rollup)
// ...
/** configuration to be merged with .eslintrc */
eslint?: Record<string, unknown>;
/** configuration to be merged with .jestrc */
jest?: Record<string, unknown>;
/** configuration to be merged with .lintstagedrc */
lintstaged?: Record<string, unknown>;
/** patterns to be added to .gitignore */
gitignore?: string[];
/** patterns to be added to .npmignore */
npmignore?: string[];
/** configuration to be merged with .presetterrc */
prettier?: Record<string, unknown>;
/** configuration to be merged with tsconfig.json */
tsconfig?: Record<string, unknown>;
/** a list of config files not to be created */
ignores?: string[];
};
/** relative path to root directories for different file types */
variable?: {
/** the directory containing the whole repository (default: .) */
root?: string;
/** the directory containing all source code (default: source) */
source?: string;
/** the directory containing all typing files (default: types) */
types?: string;
/** the directory containing all output tile (default: source) */
output?: string;
/** the directory containing all test files (default: spec) */
test?: string;
};
}
```
## Script Template Summary
- **`run build`**: Transpile source code from typescript and replace any mapped paths
- **`run clean`**: Clean up any previously transpiled code
- **`run develop -- <file path>`**: Create a service that run the specified file whenever the source has changed
- **`run test`**: Run all tests
- **`run watch`**: Rerun all tests whenever the source has change
- **`run coverage`**: Run all test with coverage report
- **`run release`**: Bump the version and automatically generate a change log
- **`run release -- --prerelease <tag>`**: Release with a prerelease tag