onlybuild 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [v1.1.0](https://github.com/neogeek/onlybuild/tree/v1.1.0) - (2024-04-26)
+
+[Full Changelog](https://github.com/neogeek/onlybuild/compare/v1.0.0...v1.1.0)
+
+- [feat] Added input arg and version, help and out flags. [#2](https://github.com/neogeek/onlybuild/pull/2)
+- [feat] Broke out build and copy methods into smaller ones. [#1](https://github.com/neogeek/onlybuild/pull/1)
+
+## [v1.0.0](https://github.com/neogeek/onlybuild/tree/v1.0.0) - (2024-04-23)
+
+- Initial release! 🎉
+
+_This changelog was generated with **[generate-local-changelog](https://github.com/neogeek/generate-local-changelog)**_

package/README.md

@@ -4,6 +4,7 @@
 
 [![Test](https://github.com/neogeek/onlybuild/actions/workflows/test.workflow.yml/badge.svg)](https://github.com/neogeek/onlybuild/actions/workflows/test.workflow.yml)
 [![Publish](https://github.com/neogeek/onlybuild/actions/workflows/publish.workflow.yml/badge.svg)](https://github.com/neogeek/onlybuild/actions/workflows/publish.workflow.yml)
+[![Documentation](https://doxdox.org/images/badge-flat.svg)](https://doxdox.org/neogeek/onlybuild)
 [![NPM version](https://img.shields.io/npm/v/onlybuild)](https://www.npmjs.org/package/onlybuild)
 [![Join the chat at https://discord.gg/nNtFsfd](https://img.shields.io/badge/discord-join%20chat-7289DA.svg)](https://discord.gg/nNtFsfd)
 
@@ -26,11 +27,14 @@
 ## Table of Contents
 
 - [Install](#install)
+- [Usage](#usage)
 - [Quick Start Guide](#quick-start-guide)
 - [Getting Started](#getting-started)
 - [File Structure](#file-structure)
 - [Ignore Files](#ignore-files)
 - [Formatting Files](#formatting-files)
+- [Watching For Changes](#watching-for-changes)
+- [Local Server](#local-server)
 - [Examples](#examples)
 - [Benchmark](#benchmark)
 - [Testing](#testing)
@@ -76,6 +80,19 @@ $ npm install onlybuild --save-dev
 $ npm run build
 ```
 
+## Usage
+
+```bash
+Usage: onlybuild <path> [options]
+
+  Options:
+
+   -h, --help            Display this help message.
+   -v, --version         Display the current installed version.
+   -o, --out             Sets build directory. Default path is build/
+   -i, --ignore          Sets ignore file path. Default path is .onlyignore
+```
+
 ## Quick Start Guide
 
 Create a new file `index.mjs` with the following contents:
@@ -142,6 +159,31 @@ import { marked } from 'marked';
 export default marked.parse(await readFile('index.md', 'utf8'));
 ```
 
+### Parse Markdown w/ Syntax Highlighting
+
+This Markdown example parses code blocks and adds CSS classes before rendering the page to HTML.
+
+```javascript
+import { readFile } from 'node:fs/promises';
+
+import { Marked } from 'marked';
+
+import { markedHighlight } from 'marked-highlight';
+import hljs from 'highlight.js';
+
+const marked = new Marked(
+  markedHighlight({
+    langPrefix: 'hljs language-',
+    highlight(code, lang, info) {
+      const language = hljs.getLanguage(lang) ? lang : 'plaintext';
+      return hljs.highlight(code, { language }).value;
+    }
+  })
+);
+
+export default marked.parse(await readFile('index.md', 'utf8'));
+```
+
 ### <code>&#96;html&#96;</code> String Template Utility
 
 The `onlybuild` library includes an optional <code>&#96;html&#96;</code> string template utility that can be used to add syntax highlighting and formatting to HTML, making it easier to author HTML in JavaScript.
@@ -156,14 +198,62 @@ Install the [lit-html](https://marketplace.visualstudio.com/items?itemName=biern
 
 ## File Structure
 
-When you run `npx onlybuild` the default export of all `.mjs` file will be captured and written to files in a `build/` directory.
+When you run `npx onlybuild`, all `.mjs` files with a `export default` that returns a string will be captured and written to the `build/` directory. All other files will be copied with the same file structure to the `build` directory unless included in the `.onlyignore` file or in a default ignored directory, indicated by a leading `_` character.
 
 If the name of your `.mjs` file is `index.mjs` the output will be saved to `index.html`, but if it's name is `something-else.mjs` the output will be saved to `something-else/index.mjs`.
 
+See the example file structure below for a more comprehensive example that includes building files and copying static files.
+
+<table>
+<tr>
+<th>
+Files
+</v>
+<th>
+Build Output
+</th>
+<tr>
+<td>
+
+```
+├── _includes
+│   └── head.mjs
+├── about
+│   └── index.mjs
+├── blog
+│   └── hello-world.mjs
+├── css
+│   └── styles.css
+├── images
+│   └── icon.png
+└── index.mjs
+```
+
+</td>
+<td>
+
+```
+├── index.html
+├── css
+│   └── styles.css
+├── images
+│   └── icon.png
+├── about
+│   └── index.html
+└── blog
+    └── hello-world
+        └── index.html
+
+```
+
+</td></tr></table>
+
 ## Ignore Files
 
 If you want to ignore files from being generated into static files or copied into the `build.` directory you can add them to an ignore file called `.onlyignore`, which has a syntax similar to [`.gitignore`](https://git-scm.com/docs/gitignore) files.
 
+As stated in the previous section, any files in a directory with a leading `_` character will be automatically ignored. Example: `_includes` or `_data`.
+
 ```
 *.md
 
@@ -174,16 +264,60 @@ LICENSE
 
 ## Formatting Files
 
-Originally, [Prettier](https://prettier.io/) was included in the build step, but it caused the build time to balloon to 3x its current time. Because of this, it was removed and is recommended to run after the build step, or not at all if it's not needed.
+If you want to reformat the HTML files in the build directory, you can use [Prettier](https://prettier.io/) after the build completes.
 
-```bash
-$ npx prettier --write "build/**/*.html"
+```json
+{
+  ...
+  "scripts": {
+    "build": "onlybuild",
+    "format": "npx prettier --write \"build/**/*.html\""
+  },
+  ...
+}
 ```
 
 If your `build/` directory is in `.gitignore` (which it probably should be) you will need to ignore the `.gitignore` file by setting the `--ignore-path` flag to something else. The file you set it to doesn't need to exist.
 
-```bash
-$ npx prettier --write --ignore-path .prettierignore "build/**/*.html"
+```json
+{
+  ...
+  "scripts": {
+    "build": "onlybuild",
+    "format": "npx prettier --write --ignore-path .prettierignore \"build/**/*.html\""
+  },
+  ...
+}
+```
+
+## Watching For Changes
+
+If you want to automatically rebuild the project when files are updated you can use [nodemon](https://nodemon.io/).
+
+```json
+{
+  ...
+  "scripts": {
+    "build": "onlybuild",
+    "watch": "npx nodemon --ext mjs,md,css --ignore ./build -x \"npm run build\""
+  },
+  ...
+}
+```
+
+## Local Server
+
+Serving the files once the build is complete is easy using the NPM package [http-server](https://github.com/http-party/http-server).
+
+```json
+{
+  ...
+  "scripts": {
+    "build": "onlybuild",
+    "serve": "npx http-server build"
+  },
+  ...
+}
 ```
 
 ## Examples

package/bin/index.js

@@ -1,16 +1,60 @@
 #!/usr/bin/env node
 
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
 import { globby } from 'globby';
 
+import parseCmdArgs from 'parse-cmd-args';
+
 import { buildFiles } from '../src/build.js';
 import { copyFiles } from '../src/copy.js';
 
+const args = parseCmdArgs(null, {
+  requireUserInput: false
+});
+
+if (args.flags['--version'] || args.flags['-v']) {
+  process.stdout.write(
+    `${
+      JSON.parse(
+        await readFile(
+          join(dirname(fileURLToPath(import.meta.url)), '../package.json'),
+          'utf8'
+        )
+      ).version
+    }\n`
+  );
+  process.exit();
+} else if (args.flags['--help'] || args.flags['-h']) {
+  process.stdout.write(`Usage: onlybuild <path> [options]
+
+  Options:
+
+   -h, --help            Display this help message.
+   -v, --version         Display the current installed version.
+   -o, --out             Sets build directory. Default path is build/
+   -i, --ignore          Sets ignore file path. Default path is .onlyignore
+`);
+  process.exit();
+}
+
+const [buildDir = 'build/'] = [args.flags['--out'], args.flags['-o']]
+  .filter(flag => typeof flag === 'string')
+  .map(String);
+
+const [ignoreFile = '.onlyignore'] = [args.flags['--ignore'], args.flags['-i']]
+  .filter(flag => typeof flag === 'string')
+  .map(String);
+
 await buildFiles(
-  await globby(['**/*.mjs', '!_*/**/*', '!node_modules/', '!build/'], {
+  await globby(['**/*.mjs', '!_*/**/*', '!node_modules/', `!${buildDir}`], {
     gitignore: true,
-    ignoreFiles: ['.onlyignore']
+    ignoreFiles: [ignoreFile],
+    cwd: args.inputs[0]
   }),
-  'build/'
+  buildDir
 );
 
 await copyFiles(
@@ -22,14 +66,15 @@ await copyFiles(
       '!package.json',
       '!package-lock.json',
       '!node_modules/',
-      '!build/'
+      `!${buildDir}`
     ],
     {
       gitignore: true,
-      ignoreFiles: ['.onlyignore']
+      ignoreFiles: [ignoreFile],
+      cwd: args.inputs[0]
     }
   ),
-  'build/'
+  buildDir
 );
 
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "onlybuild",
   "description": "A zero-config cli for building static websites.",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "engines": {
     "node": ">=20.x"
   },
@@ -12,7 +12,8 @@
   "main": "./src/index.js",
   "license": "MIT",
   "dependencies": {
-    "globby": "14.0.1"
+    "globby": "14.0.1",
+    "parse-cmd-args": "5.0.1"
   },
   "scripts": {
     "test": "node --test"

package/src/build.js

@@ -2,26 +2,45 @@ import { writeFile, mkdir } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
 
 /**
- * @param {string[]} paths
+ * Write the file to the build directory while creating the directory, recursively, if it doesn't exist.
+ *
+ * @param {string} path
  * @param {string} buildDir
+ * @param {string} contents
  */
-export const buildFiles = async (paths, buildDir) => {
-  await Promise.all(
-    paths.map(async path => {
-      const filename = basename(path, '.mjs');
+export const writeFileAndMakeDir = async (path, buildDir, contents) => {
+  const filename = basename(path, '.mjs');
 
-      const directory =
-        filename === 'index'
-          ? join(buildDir, dirname(path))
-          : join(buildDir, dirname(path), filename);
+  const directory =
+    filename === 'index'
+      ? join(buildDir, dirname(path))
+      : join(buildDir, dirname(path), filename);
 
-      const html = (await import(resolve(path))).default;
+  await mkdir(directory, { recursive: true });
+
+  await writeFile(join(directory, 'index.html'), contents);
+};
+
+/**
+ * Import the default export of a JavaScript file and check that the default export is a string before writing the contents to a build file.
+ *
+ * @param {string} path
+ * @param {string} buildDir
+ */
+export const buildFile = async (path, buildDir) => {
+  const contents = (await import(resolve(path))).default;
 
-      if (typeof html === 'string') {
-        await mkdir(directory, { recursive: true });
+  if (typeof contents === 'string') {
+    await writeFileAndMakeDir(path, buildDir, contents);
+  }
+};
 
-        await writeFile(join(directory, `index.html`), html);
-      }
-    })
-  );
+/**
+ * Iterate over all the file paths and write them to the build directory.
+ *
+ * @param {string[]} paths
+ * @param {string} buildDir
+ */
+export const buildFiles = async (paths, buildDir) => {
+  await Promise.all(paths.map(async path => await buildFile(path, buildDir)));
 };

package/src/copy.js

@@ -2,15 +2,25 @@ import { copyFile, mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
 /**
+ * Copy the file to the build directory while creating the directory, recursively, if it doesn't exist.
+ *
+ * @param {string} path
+ * @param {string} buildDir
+ */
+export const copyFileAndMakeDir = async (path, buildDir) => {
+  await mkdir(join(buildDir, dirname(path)), { recursive: true });
+
+  await copyFile(path, join(buildDir, path));
+};
+
+/**
+ * Iterate over all the file paths and copy them to the build directory.
+ *
  * @param {string[]} paths
  * @param {string} buildDir
  */
 export const copyFiles = async (paths, buildDir) => {
   await Promise.all(
-    paths.map(async path => {
-      await mkdir(join(buildDir, dirname(path)), { recursive: true });
-
-      await copyFile(path, join(buildDir, path));
-    })
+    paths.map(async path => await copyFileAndMakeDir(path, buildDir))
   );
 };

package/src/html.js

@@ -1,4 +1,6 @@
 /**
+ * String template utility that adds syntax highlighting and formatting in text editors.
+ *
  * @param {TemplateStringsArray} strings
  * @param {any[]} values
  */