@changke/staticnext-build 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.0
+2023-06-23
+### Added
+- Initial release
+- Extracted the build code and related npm packages from `@changke/staticnext-seed` project into this standalone package

package/README.md

@@ -0,0 +1,3 @@
+# StaticNext Build
+
+A wrapper that invokes various packages to build static assets, extracted from `@changke/staticnext-seed` project.

package/build.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+import {argv} from 'node:process';
+
+import config from './lib/config.mjs';
+
+import clean from './lib/tasks/clean.mjs';
+import copy from './lib/tasks/copy.mjs';
+import markdown from './lib/tasks/markdown.mjs';
+import prototype from './lib/tasks/prototype.mjs';
+import scripts from './lib/tasks/scripts.mjs';
+import setEnvDev from './lib/tasks/set-env-dev.mjs';
+import setEnvProd from './lib/tasks/set-env-prod.mjs';
+import styles from './lib/tasks/styles.mjs';
+
+const taskName = argv[2]?.toLowerCase() || 'dev';
+
+// load config data
+const conf = await config.loadConfig();
+
+const taskEnded = taskName => {
+  console.timeEnd(taskName);
+};
+
+// Set parameters of each task
+const tasks = {
+  clean: () => clean([`${conf.targetRoot}/*`]),
+  copy: () => copy([
+    {sources: [`${conf.sourceRoot}/*`, `!${conf.sourceRoot}/*.d.ts`], target: conf.targetRoot},
+    {sources: `${conf.sourcePath.assets}/**/*`, target: conf.targetPath.assets},
+    {sources: `${conf.sourcePath.modules}/**/assets/**/*`, target: conf.targetPath.moduleAssets}
+  ]),
+  markdown: () => markdown(
+    conf.sourcePath.markdown,
+    [conf.sourcePath.prototype, conf.sourcePath.modules],
+    conf.njkGlobals,
+    conf.targetPath.markdown
+  ),
+  prototype: () => prototype(
+    conf.sourcePath.prototype,
+    [conf.sourcePath.modules],
+    conf.njkGlobals,
+    conf.targetPath.prototype
+  ),
+  scripts: () => scripts(conf.scriptEntries(conf.moduleEntries), conf.targetPath.assets),
+  styles: () => styles([
+    `${conf.sourcePath.css}/brands/*.css`,
+    `${conf.sourcePath.css}/index.css`,
+    `${conf.sourcePath.modules}/**/*.css`,
+    `!${conf.sourcePath.modules}/**/_*.css`
+  ], conf.targetPath.assets)
+};
+
+const paraDev = () => {
+  return Promise.all([
+    tasks.markdown(),
+    tasks.prototype(),
+    tasks.styles(),
+    tasks.scripts()
+  ]);
+};
+
+const paraProd = () => {
+  return Promise.all([
+    tasks.markdown(),
+    tasks.styles(),
+    tasks.scripts()
+  ]);
+};
+
+const dev = () => {
+  return setEnvDev().then(tasks.clean).then(tasks.copy).then(paraDev);
+};
+
+const prod = () => {
+  return setEnvProd().then(tasks.clean).then(tasks.copy).then(paraProd);
+};
+
+const taskMap = {
+  'clean': tasks.clean,
+  'copy': tasks.copy,
+  'markdown': tasks.markdown,
+  'prototype': tasks.prototype,
+  'scripts': tasks.scripts,
+  'setenvdev': setEnvDev,
+  'setenvprod': setEnvProd,
+  'styles': tasks.styles,
+  'dev': dev,
+  'prod': prod
+};
+
+const task = taskMap[taskName];
+
+console.log('+++ SN Build +++');
+console.time(taskName);
+console.log(`Task "${taskName}" started...`);
+task().then(() => {
+  taskEnded(taskName);
+}).catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/lib/config.mjs

@@ -0,0 +1,25 @@
+import {cwd} from 'node:process';
+
+import vars from './vars.mjs';
+
+class Config {
+  customConfigFile = '/sn-config.mjs';
+
+  async loadConfig(configFile) {
+    const defaultConf = vars;
+    try {
+      // try loading custom config file
+      const cf = configFile || `${cwd()}${this.customConfigFile}`;
+      const mod = await import(cf);
+      const customConf = mod.default;
+      return Object.assign({}, defaultConf, customConf);
+    } catch (e) {
+      // file not exist
+      return defaultConf;
+    }
+  }
+}
+
+const config = new Config();
+
+export default config;

package/lib/is-prod.mjs

@@ -0,0 +1,3 @@
+export default function() {
+  return (process.env.NODE_ENV === 'production');
+}

package/lib/tasks/clean.mjs

@@ -0,0 +1,15 @@
+import {deleteAsync} from 'del';
+
+/**
+ * Clean the target directory
+ *
+ * @param {(string|string[])} targetPath
+ * @returns {Promise<string[]>}
+ */
+const clean = (targetPath) => {
+  console.log('=> clean');
+  return deleteAsync(targetPath);
+};
+
+export {clean};
+export default clean;

package/lib/tasks/copy.mjs

@@ -0,0 +1,21 @@
+import cpy from 'cpy';
+
+/**
+ * @typedef {Object} STPair
+ * @property {(string|string[])} sources
+ * @property {string} target
+ */
+
+/**
+ * Copy (different) assets
+ *
+ * @param {STPair[]} sourceTargetPairs
+ * @return {Promise<Awaited<unknown>[]>}
+ */
+const copy = (sourceTargetPairs) => {
+  console.log('=> copy');
+  return Promise.all(sourceTargetPairs.map(pair => cpy(pair.sources, pair.target)));
+};
+
+export {copy};
+export default copy;

package/lib/tasks/markdown.mjs

@@ -0,0 +1,69 @@
+import {globby} from 'globby';
+import {readFile} from 'node:fs/promises';
+import {marked} from 'marked';
+import {markedXhtml} from 'marked-xhtml';
+import njk from 'nunjucks';
+
+import {createAndWriteToFile, getTargetPathString} from '../utils.mjs';
+
+marked.use({
+  headerIds: false,
+  mangle: false
+}, markedXhtml());
+
+const {Environment, FileSystemLoader} = njk;
+
+const njkWrapper = {
+  top: '{% extends "templates/markdown.njk" %}{% block title %}{{ pageTitle }}{% endblock %}{% block content %}',
+  bottom: '{% endblock %}'
+};
+
+const getPageTitle = content => {
+  let t = 'Untitled';
+  if (content.length > 1) {
+    const firstLine = content.split('\n')[0];
+    if (firstLine) {
+      t = firstLine.replace('# ', ''); // First line MUST be a level 1 heading!
+    }
+  }
+  return t;
+};
+
+/**
+ * Generate docs using markdown and Nunjucks
+ *
+ * @param {string} mdSourcePathRoot
+ * @param {string[]} njkPaths
+ * @param {Object} njkGlobals
+ * @param {string} mdTargetPath
+ * @return {Promise<string[]>}
+ */
+const markdown = (mdSourcePathRoot, njkPaths, njkGlobals, mdTargetPath) => {
+  console.log('=> markdown');
+  return globby(`${mdSourcePathRoot}/**/*.md`).then(docs => {
+    const njkEnv = new Environment(new FileSystemLoader(njkPaths, {}));
+    for (const [k, v] of Object.entries(njkGlobals)) {
+      njkEnv.addGlobal(k, v);
+    }
+    docs.forEach(async (doc) => {
+      const mdContent = await readFile(doc, {encoding: 'utf8'});
+      const html = marked.parse(mdContent);
+      const pageTitle = getPageTitle(mdContent);
+      const njkContent = njkWrapper.top + html + njkWrapper.bottom;
+      const res = njkEnv.renderString(njkContent, {
+        'pageTitle': pageTitle
+      });
+      const target = getTargetPathString(
+        doc,
+        mdSourcePathRoot,
+        mdTargetPath,
+        'md',
+        'html'
+      );
+      await createAndWriteToFile(target, res);
+    });
+  });
+};
+
+export {markdown};
+export default markdown;

package/lib/tasks/prototype.mjs

@@ -0,0 +1,41 @@
+import njk from 'nunjucks';
+import {globby} from 'globby';
+import {readFile} from 'node:fs/promises';
+
+import {getTargetPathString, createAndWriteToFile} from '../utils.mjs';
+
+const {Environment, FileSystemLoader} = njk;
+
+/**
+ * Generate static pages with Nunjucks
+ *
+ * @param {string} prototypeSourcePathRoot
+ * @param {string[]} njkPaths
+ * @param {Object} njkGlobals
+ * @param {string} prototypeTargetPath
+ * @return {Promise<string[]>}
+ */
+const prototype = (prototypeSourcePathRoot, njkPaths, njkGlobals, prototypeTargetPath) => {
+  console.log('=> prototype');
+  return globby(`${prototypeSourcePathRoot}/pages/**/*.njk`).then(pages => {
+    const njkEnv = new Environment(new FileSystemLoader([prototypeSourcePathRoot].concat(njkPaths), {}));
+    for (const [k, v] of Object.entries(njkGlobals)) {
+      njkEnv.addGlobal(k, v);
+    }
+    pages.forEach(async (page) => {
+      const pageContent = await readFile(page, {encoding: 'utf8'});
+      const res = njkEnv.renderString(pageContent);
+      const targetFile = getTargetPathString(
+        page,
+        `${prototypeSourcePathRoot}/pages`,
+        prototypeTargetPath,
+        'njk',
+        'html'
+      );
+      await createAndWriteToFile(targetFile, res);
+    });
+  });
+};
+
+export {prototype};
+export default prototype;

package/lib/tasks/scripts.mjs

@@ -0,0 +1,27 @@
+import {build} from 'esbuild';
+
+import isEnvProd from '../is-prod.mjs';
+
+/**
+ * Transpile / bundle JS files using esbuild
+ *
+ * @param {string[]} entries
+ * @param {string} targetPath
+ * @return {Promise}
+ */
+const esm = (entries, targetPath) => {
+  console.log('=> scripts');
+  return build({
+    entryPoints: entries,
+    bundle: true,
+    format: 'esm',
+    target: 'es2021',
+    splitting: true,
+    outdir: targetPath,
+    minify: isEnvProd(), // only minify in prod build
+    sourcemap: !isEnvProd() // only create sourcemaps in dev build
+  });
+};
+
+export {esm};
+export default esm;

package/lib/tasks/set-env-dev.mjs

@@ -0,0 +1,8 @@
+const setEnvDev = () => {
+  return new Promise((resolve) => {
+    process.env.NODE_ENV = 'development';
+    resolve();
+  });
+};
+
+export default setEnvDev;

package/lib/tasks/set-env-prod.mjs

@@ -0,0 +1,8 @@
+const setEnvProd = () => {
+  return new Promise((resolve) => {
+    process.env.NODE_ENV = 'production';
+    resolve();
+  });
+};
+
+export default setEnvProd;

package/lib/tasks/styles.mjs

@@ -0,0 +1,28 @@
+import {build} from 'esbuild';
+import {globby} from 'globby';
+
+import isEnvProd from '../is-prod.mjs';
+
+/**
+ * Use esbuild to bundle CSS files
+ *
+ * @param {string[]} sources
+ * @param {string} targetPath
+ * @return {Promise}
+ */
+const styles = (sources, targetPath) => {
+  console.log('=> styles');
+  return globby(sources).then(entries => {
+    return build({
+      entryPoints: entries,
+      bundle: true,
+      target: 'es2021',
+      outdir: targetPath,
+      sourcemap: !isEnvProd(),
+      minify: isEnvProd()
+    });
+  });
+};
+
+export {styles};
+export default styles;

package/lib/utils.mjs

@@ -0,0 +1,23 @@
+import {access, mkdir, writeFile} from 'node:fs/promises';
+import * as path from 'node:path';
+
+const getTargetPathString = (sourcePath, sourceRoot, targetRoot, srcExt, tgtExt) => {
+  const baseName = path.basename(sourcePath, `.${srcExt}`);
+  const dirName = path.dirname(sourcePath).replace(sourceRoot, '');
+  return path.join(targetRoot, dirName, `${baseName}.${tgtExt}`);
+};
+
+const createAndWriteToFile = async (filePath, fileContent) => {
+  const tp = path.dirname(filePath);
+  try {
+    await access(tp);
+  } catch {
+    await mkdir(tp, {recursive: true});
+  }
+  await writeFile(filePath, fileContent, {flag: 'w+'});
+};
+
+export {
+  getTargetPathString,
+  createAndWriteToFile
+};

package/lib/vars.mjs

@@ -0,0 +1,103 @@
+/**
+ * @typedef {Object} PathPart
+ * @property {string} assets Path for general static assets
+ * @property {string=} css Path for CSS files
+ * @property {string=} js Path for JS files
+ * @property {string=} modules Path for module directories / files
+ * @property {string=} moduleAssets Path for assets of individual modules
+ * @property {string=} prototype Path for prototype (HTML) files
+ * @property {string=} test Path for unit-test related files
+ * @property {string=} markdown Path for markdown files
+ */
+
+/**
+ * @typedef {Function} ScriptEntryFunc
+ * @param {string[]} modEntries
+ * @param {string=} mainEntry
+ * @return {string[]}
+ */
+
+/**
+ * @typedef {Object} SNConfig
+ * @property {string} sourceRoot Root dir of source
+ * @property {string} targetRoot Root dir for output (target)
+ * @property {PathPart} sourcePath Paths of different types of source files
+ * @property {PathPart} targetPath Paths for different output files
+ * @property {string[]} tenants Theme-names
+ * @property {string[]} moduleEntries List of input files of modules e.g. 'mod-foo/foo.ts'
+ * @property {string} mainEntryFile The entry point of all JS e.g. main.ts
+ * @property {ScriptEntryFunc} scriptEntries Inputs of source files for esbuild
+ * @property {string} assetsUrlPath Path of assets used in URL for resource loading etc.
+ * @property {boolean} markdownEnabled Enable markdown feature or not
+ * @property {Record<string, string>} njkGlobals Global variables assigned to Nunjucks compiler
+ */
+
+// default config values
+const moduleEntries = [];
+
+const sourceRoot = './src/main/webapp';
+const targetRoot = './tgt/static';
+
+/** @type {PathPart} */
+const sourcePath = {
+  assets: `${sourceRoot}/assets`,
+  css: `${sourceRoot}/css`,
+  js: `${sourceRoot}/js`,
+  modules: `${sourceRoot}/modules`,
+  prototype: `${sourceRoot}/prototype`,
+  test: `${sourceRoot}/test`,
+  markdown: `${sourceRoot}/md`
+};
+
+const targetAssetsRoot = `${targetRoot}/assets/_sn_`;
+const targetPath = {
+  assets: targetAssetsRoot,
+  css: `${targetAssetsRoot}/css`,
+  js: `${targetAssetsRoot}/js`,
+  moduleAssets: `${targetAssetsRoot}/modules`,
+  prototype: `${targetRoot}/prototype`,
+  markdown: `${targetRoot}/docs`
+};
+
+// "themes", not in use, replaced with brands directory
+const tenants = ['one', 'two', 'three'];
+
+const mainEntryFile = `${sourcePath.js}/main.ts`;
+
+// also add the main entry file
+/** @type {ScriptEntryFunc} */
+const scriptEntries = (modEntries, mainEntry = mainEntryFile) => {
+  // For code splitting, as input config for esbuild
+  const moduleEntryFiles = modEntries.map(f => {
+    return `${sourcePath.modules}/${f}`;
+  });
+  return [mainEntry].concat(moduleEntryFiles);
+};
+
+// To get relative path of assets
+const assetsUrlPath = '/assets/_sn_';
+
+// Markdown enabled?
+const markdownEnabled = true;
+
+// globals for Nunjucks
+const njkGlobals = {
+  'assetsUrlPath': assetsUrlPath
+};
+
+/** @type {SNConfig} */
+const config = {
+  sourceRoot,
+  targetRoot,
+  sourcePath,
+  targetPath,
+  tenants,
+  moduleEntries,
+  mainEntryFile,
+  scriptEntries,
+  assetsUrlPath,
+  markdownEnabled,
+  njkGlobals
+};
+
+export default config;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@changke/staticnext-build",
+  "version": "0.1.0",
+  "description": "Build scripts extracted from StaticNext seed project",
+  "main": "index.js",
+  "scripts": {
+    "lint": "eslint --ext .mjs . lib test",
+    "test": "mocha",
+    "prepublishOnly": "npm run lint && npm run test"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "bin": {
+    "sn-build": "./build.mjs"
+  },
+  "keywords": [],
+  "author": "@changke",
+  "license": "ISC",
+  "type": "module",
+  "devDependencies": {
+    "eslint": "^8.43.0",
+    "mocha": "^10.2.0"
+  },
+  "dependencies": {
+    "cpy": "^10.1.0",
+    "del": "^7.0.0",
+    "esbuild": "^0.18.6",
+    "globby": "^13.2.0",
+    "marked": "^5.1.0",
+    "marked-xhtml": "^1.0.1",
+    "nunjucks": "^3.2.4"
+  }
+}