https://github.com/omar-azmi/build_tools_ts
general deno build tool scripts which I practically use in all of my typescript repos
https://github.com/omar-azmi/build_tools_ts
build-tools bundler converter deno dnt docs-generator esbuild npm typedoc typescript
Last synced: 11 months ago
JSON representation
general deno build tool scripts which I practically use in all of my typescript repos
- Host: GitHub
- URL: https://github.com/omar-azmi/build_tools_ts
- Owner: omar-azmi
- License: other
- Created: 2024-03-28T06:51:25.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-25T22:21:43.000Z (over 1 year ago)
- Last Synced: 2024-11-25T23:41:55.503Z (over 1 year ago)
- Topics: build-tools, bundler, converter, deno, dnt, docs-generator, esbuild, npm, typedoc, typescript
- Language: TypeScript
- Homepage: https://omar-azmi.github.io/build_tools_ts/
- Size: 5.99 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license.md
- Code of conduct: .github/code_of_conduct.md
Awesome Lists containing this project
README
# @oazmi/build-tools
This package contains various convenience tools for codebase transformation, documentation generation, and code bundling.
Under the hood, it relies on:
- [`esbuild`](https://www.npmjs.com/package/esbuild) + [`esbuild-deno-loader`](https://jsr.io/@luca/esbuild-deno-loader) for bundling ({@link dist!}).
- [`dnt`](https://jsr.io/@deno/dnt) for deno to node project transformation ({@link docs!}).
- [`typedoc`](https://www.npmjs.com/package/typedoc) for documentation generation ({@link npm!}).
## Building Typescript Documentation
### Through the CLI
To generate documentation for your typescript project through the shell, simply run:
```shell
deno run -A "jsr:@oazmi/build-tools/cli/docs"
```
You may also provide a json file containing a documentation-generation configuration, by passing its location using the cli `--config="./path/to/config.json"`, and then using the schema in {@link cli/docs!CliConfigJson | `CliConfigJson`} to configure the json bundling options.
See the {@link cli/docs!} module's documentation for further reading.
### Through Scripting
To generate documentation through scripting, use the {@link docs!buildDocs | `buildDocs`} function.
Read the {@link docs!} module's documentation for advanced usage.
An example to get a taste of the configurable options:
```ts
import { buildDocs, type BuildDocsConfig, defaultBuildDocsConfig } from "jsr:@oazmi/build-tools/docs"
const my_config: BuildDocsConfig = {
...defaultBuildDocsConfig,
dir: "./mydocs/",
site: "./mydocs/",
preserveTemporary: false,
typedoc: {
// place optional typedoc configurations here
githubPages: true,
},
text: ["./helloworld.txt", "Konichiwa Meena-San!\nShine' Kuda Sai Meena-San!\nSosshtte Arigato yo Meena-San Desu Desu!"],
}
const docs_artifacts = await buildDocs(my_config)
alert("press any button to delete the generated docs in:", my_config.dir)
// cleanup the generated documentation html site under "./mydocs/"
docs_artifacts.cleanup()
```
## Transforming Deno project to Node project
### Through the CLI
To transform your deno project to a node-based project through the shell, simply run:
```shell
deno run -A "jsr:@oazmi/build-tools/cli/npm" --install
```
You may also provide a json file containing a node-project-generation configuration, by passing its location using the cli `--config="./path/to/config.json"`, and then using the schema in {@link cli/npm!CliConfigJson | `CliConfigJson`} to configure the json bundling options.
See the {@link cli/npm!} module's documentation for further reading.
### Through Scripting
To transform to a node-based project through scripting, use the {@link npm!buildNpm | `buildNpm`} function.
Read the {@link npm!} module's documentation for advanced usage.
An example to catch a whiff of stinky node's configurable options:
```ts
import { buildNpm, type BuildNpmConfig, defaultBuildNpmConfig } from "jsr:@oazmi/build-tools/npm"
const my_config: BuildNpmConfig = {
...defaultBuildNpmConfig,
dir: "./npm-release/",
dnt: {
// place optional dnt configurations here
typeCheck: true,
declaration: "inline",
test: true,
skipNpmInstall: false,
},
text: ["./helloworld.txt", "Konichiwa Meena-San!\nShine' Kuda Sai Meena-San!\nSosshtte Arigato yo Meena-San Desu Desu!"],
}
const npm_artifacts = await buildNpm(my_config)
alert("press any button to delete the generated npm-build in:", my_config.dir)
// cleanup the generated npm-build under "./npm-release/"
npm_artifacts.cleanup()
```
## Bundle Source Code to Javascript
### Through the CLI
To create a bundled and minified distribution of your deno project's exports through the shell, simply run:
```shell
deno run -A "jsr:@oazmi/build-tools/cli/dist"
```
Check out the {@link cli/dist!CliArgs | `CliArgs`} interface for a list of configurable options via command line switches (i.e. `--command-name="command_value"`)
You may also provide a json file containing a bundling configuration, by passing its location using the cli `--config="./path/to/config.json"`, and then using the schema in {@link cli/dist!CliConfigJson | `CliConfigJson`} to configure the json bundling options.
See the {@link cli/dist!} module's documentation for further reading.
### Through Scripting
To bundle your source code to javascript through scripting, use the {@link dist!buildDist | `buildDist`} function for single-pass builds, and for double-pass builds use: {@link dist!bundle | `bundle`} + {@link dist!transform | `transform`} + {@link funcdefs!createFiles | `createFiles`} sequentially.
Read the {@link dist!} module's documentation for advanced usage.
An example to get a flavor of the configurable options:
```ts
import { buildDist, type BuildDistConfig, defaultBuildDistConfig, esStop } from "jsr:@oazmi/build-tools/dist"
const my_config: BuildDistConfig = {
...defaultBuildDistConfig,
// when no input files are provided, the function reads your "deno.json" file to use its "exports" field as the input.
input: {
"my-lib.js": "./src/mod.ts",
"plugins/hello.js": "./src/plugins/hello.ts",
"plugins/world.js": "./src/plugins/world.ts",
},
deno: "./deno.json",
dir: "./dist/",
log: "verbose",
// enabling `splitting` makes the `input` entrypoints use the same source for shared code.
esbuild: { splitting: true },
}
await buildDist(my_config)
// your output files are now saved to: "./dist/my-lib.js", "./dist/plugins/hello.js", and "./dist/plugins/world.js"
// it is important that you stop esbuild manually, otherwise the deno process will not quit automatically.
await esStop()
```