@oazmi/build-tools

This package contains various convenience tools for codebase transformation, documentation generation, and code bundling.

Under the hood, it relies on:

• esbuild + esbuild-deno-loader for bundling ( dist!).
• dnt for deno to node project transformation ( docs!).
• typedoc for documentation generation ( npm!).

Building Typescript Documentation

Through the CLI

To generate documentation for your typescript project through the shell, simply run:

deno run -A "jsr:@oazmi/build-tools/cli/docs"
Copy

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 CliConfigJson to configure the json bundling options.
See the cli/docs! module's documentation for further reading.

Through Scripting

To generate documentation through scripting, use the buildDocs function.
Read the docs! module's documentation for advanced usage.

An example to get a taste of the configurable options:

import { buildDocs, defaultBuildDocsConfig, type BuildDocsConfig } 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()
Copy

Transforming Deno project to Node project

Through the CLI

To transform your deno project to a node-based project through the shell, simply run:

deno run -A "jsr:@oazmi/build-tools/cli/npm" --install
Copy

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 CliConfigJson to configure the json bundling options.
See the cli/npm! module's documentation for further reading.

Through Scripting

To transform to a node-based project through scripting, use the buildNpm function.
Read the npm! module's documentation for advanced usage.

An example to catch a whiff of stinky node's configurable options:

import { buildNpm, defaultBuildNpmConfig, type BuildNpmConfig } 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()
Copy

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:

deno run -A "jsr:@oazmi/build-tools/cli/dist"
Copy

Check out the 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 CliConfigJson to configure the json bundling options.
See the cli/dist! module's documentation for further reading.

Through Scripting

To bundle your source code to javascript through scripting, use the buildDist function for single-pass builds, and for double-pass builds use: bundle + transform + createFiles sequentially.
Read the dist! module's documentation for advanced usage.

An example to get a flavor of the configurable options:

import { buildDist, esStop, defaultBuildDistConfig, type BuildDistConfig } 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()
Copy