JSPM

Common build tools for extra-* packages.
📦 NPM, 📜 Files, 📰 Docs.

Stability: Experimental.

Why do packages need to be built? For TypeScript-based source libraries (such as this) our main priority is to generate JavaScript file(s) which can be imported from the runtime (Node.js), and publish them to a package registry such as NPM. In addition we might like to generate associated type declarations (.d.ts file), which is one of the reasons behind choosing to write in TypeScript. We might also like to bundle all scripts (and type declarations) into a single file to help reduce package size, dependencies, or eliminate unused code.

Documentation plays a key role in reducing the amount of time spent on Stack Overflow, and thus must be maintained at all costs. Instead of manually updating it, most developers choose to generate this from documentation comments in the code. An Index can be added to the README file that links to documention. Thus we have a new build step. In addition, we might like to update package metadata (in package.json or GitHub repo), build source files for another platform (such as the web), update package version automatically, generate wiki files (for code examples), or publish to GitHub packages.

This package provides utility functions for all of these operations, and more. The previous version of this package provided a CLI for all of these operations, but was inflexible in its design (it could only be used when the source code was arranged is a very specific way). This redesigned version provides a JavaScipt API instead that allows for significant customization, in addition to providing a number of helper functions commonly used in build steps. Build steps can be written in a script file, say build.js, and executed on a CI system such as GitHub Actions using .github/workflows/*.yml.

Behind the dial, these are the gears that make this package tick. TypeScript is compiled with tsc, bundled with rollup, webified with browserify and terser. Documentation is generated with typedoc, which is also used to obtain DocsDetails in order to update index table in README using extra-markdown-text, generate wiki files, and update package metadata locally and on GitHub repo using @octokit/rest. Updating of package versions is achieved with npm view and semver. To spice up the console with colors, kleur is used.

The goals for the future include generating example file for RunKit, linking wiki from JsDoc, and duplicating example code from wiki to JsDoc. Did you find a bug? Or have a feature request?

const build = require('extra-build');


// 1. Set version and publish package.
var m = build.readMetadata('.');
// → {name, version, description, ...}
m.version = '2.0.0';
build.writeMetadata('.', m);
build.publish('.');
build.publishGithub('.', 'owner');


// 2. Publish next version, update github details.
var m   = build.readMetadata('.');
var ver = build.nextUnpublishedVersion(m.name, m.version);
m.version = ver;
build.writeMetadata('.', m);
build.publish('.');
build.publishGithub('.', 'owner');
build.updateGithubRepoDetails();


// 3. Update keywords for package.
var m  = build.readMetadata('.');
var p  = build.loadDocs(['src/index.ts']);
var ds = p.children.map(build.docsDetails);
var s = new Set([...m.keywords, ...ds.map(d => d.name)]);
m.keywords = Array.from(s);
build.writeMetadata('.', m);


// 4. Restore package.json after publishing with updated version.
var _package = build.readDocument('package.json');
var m = build.readMetadata('.');
m.version = '2.0.0';
build.writeMetadata('.', m);
build.publish('.');
build.writeDocument(_package);


// 5. Update README index table.
var owner = 'owner', repo = 'repo';
var p  = build.loadDocs(['src/index.ts']);
var ds = p.children.map(build.docsDetails);
var re = /namespace|function/i;
var dm = new Map(ds.map(d => [d.name, d]));
var txt = build.readFileText('README.md');
txt = build.wikiUpdateIndex(txt, dm, d => re.test(d.kind));
txt = build.wikiUpdateLinkReferences(txt, dm, {owner, repo});
build.writeFileText('README.md', txt);

Index