onlybuild 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [v1.2.0](https://github.com/neogeek/onlybuild/tree/v1.2.0) - (2024-05-07)
+
+[Full Changelog](https://github.com/neogeek/onlybuild/compare/v1.1.0...v1.2.0)
+
+- [feat] Added .env support. [#10](https://github.com/neogeek/onlybuild/pull/10)
+- [hotfix] Added a prepare build target. [#9](https://github.com/neogeek/onlybuild/pull/9)
+- [hotfix] Fix permissions on bin file after build. [#8](https://github.com/neogeek/onlybuild/pull/8)
+- [feat] Converted project to typescript. [#7](https://github.com/neogeek/onlybuild/pull/7)
+- [hotfix] Updated packages. [#6](https://github.com/neogeek/onlybuild/pull/6)
+- [hotfix] Disable gitignore in globby. [#3](https://github.com/neogeek/onlybuild/pull/3)
+
+## [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
@@ -197,13 +331,13 @@ $ npx prettier --write --ignore-path .prettierignore "build/**/*.html"
 ## Benchmark
 
 > [!NOTE]
-> Each run (for onlybuild only) was repeated 5 times and the average time was selected. This result set was generated on a MacBook Air (M1, 2020), macOS Sonoma 14.4.1, 8 GB memory.
+> Each run (for `onlybuild` only) was repeated 5 times and the lowest/fastest time was selected. This result set was generated on a MacBook Air (M1, 2020), macOS Sonoma 14.4.1, 8 GB memory.
 
 Times shown are in seconds. Lower is better.
 
 | Markdown Files                                 |      250 |      500 |     1000 |     2000 |     4000 |
 | ---------------------------------------------- | -------: | -------: | -------: | -------: | -------: |
-| onlybuild                                      |  `0.321` |  `0.390` |  `0.554` |  `0.892` |  `1.717` |
+| onlybuild                                      |  `0.296` |  `0.356` |  `0.512` |  `0.770` |  `1.309` |
 | [Hugo](https://gohugo.io/) v0.101.0            |  `0.071` |  `0.110` |  `0.171` |  `0.352` |  `0.684` |
 | [Eleventy](https://www.11ty.dev/) 1.0.1        |  `0.584` |  `0.683` |  `0.914` |  `1.250` |  `1.938` |
 | [Astro](https://astro.build/) 1.0.1            |  `2.270` |  `3.172` |  `5.098` |  `9.791` | `22.907` |

package/dist/bin/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+export {};

package/dist/bin/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import 'dotenv/config';
+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/', `!${buildDir}`], {
+    gitignore: false,
+    ignoreFiles: [ignoreFile],
+    cwd: args.inputs[0]
+}), buildDir);
+await copyFiles(await globby([
+    '**/*',
+    '!**/*.mjs',
+    '!_*/**/*',
+    '!package.json',
+    '!package-lock.json',
+    '!node_modules/',
+    `!${buildDir}`
+], {
+    gitignore: false,
+    ignoreFiles: [ignoreFile],
+    cwd: args.inputs[0]
+}), buildDir);

package/dist/src/build.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 declare const writeFileAndMakeDir: (path: string, buildDir: string, contents: string) => Promise<void>;
+/**
+ * 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 declare const buildFile: (path: string, buildDir: string) => Promise<void>;
+/**
+ * Iterate over all the file paths and write them to the build directory.
+ *
+ * @param {string[]} paths
+ * @param {string} buildDir
+ */
+export declare const buildFiles: (paths: string[], buildDir: string) => Promise<void>;

package/dist/src/build.js

@@ -0,0 +1,38 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+/**
+ * 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 writeFileAndMakeDir = async (path, buildDir, contents) => {
+    const filename = basename(path, '.mjs');
+    const directory = filename === 'index'
+        ? join(buildDir, dirname(path))
+        : join(buildDir, dirname(path), filename);
+    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 contents === 'string') {
+        await writeFileAndMakeDir(path, buildDir, contents);
+    }
+};
+/**
+ * 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/dist/src/copy.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copy the file to the build directory while creating the directory, recursively, if it doesn't exist.
+ *
+ * @param {string} path
+ * @param {string} buildDir
+ */
+export declare const copyFileAndMakeDir: (path: string, buildDir: string) => Promise<void>;
+/**
+ * Iterate over all the file paths and copy them to the build directory.
+ *
+ * @param {string[]} paths
+ * @param {string} buildDir
+ */
+export declare const copyFiles: (paths: string[], buildDir: string) => Promise<void>;

package/dist/src/copy.js

@@ -0,0 +1,21 @@
+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 copyFileAndMakeDir(path, buildDir)));
+};

package/dist/src/html.d.ts

@@ -0,0 +1,7 @@
+/**
+ * String template utility that adds syntax highlighting and formatting in text editors.
+ *
+ * @param {TemplateStringsArray} strings
+ * @param {any[]} values
+ */
+export declare const html: (strings: TemplateStringsArray, ...values: any[]) => string;

package/dist/src/html.js

@@ -0,0 +1,10 @@
+/**
+ * String template utility that adds syntax highlighting and formatting in text editors.
+ *
+ * @param {TemplateStringsArray} strings
+ * @param {any[]} values
+ */
+export const html = (strings, ...values) => {
+    const processedValues = values.map(value => Array.isArray(value) ? value.join('') : value);
+    return strings.reduce((prev, curr, i) => `${prev}${curr}${processedValues[i] || ''}`, '');
+};

package/dist/src/index.js

@@ -0,0 +1 @@
+export { html } from './html.js';

package/package.json

@@ -1,21 +1,35 @@
 {
   "name": "onlybuild",
   "description": "A zero-config cli for building static websites.",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "engines": {
     "node": ">=20.x"
   },
   "type": "module",
   "bin": {
-    "onlybuild": "./bin/index.js"
+    "onlybuild": "dist/bin/index.js"
   },
-  "main": "./src/index.js",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./build": "./dist/src/build.js",
+    "./copy": "./dist/src/copy.js"
+  },
+  "types": "./dist/src/index.d.ts",
   "license": "MIT",
   "dependencies": {
-    "globby": "14.0.1"
+    "dotenv": "16.4.5",
+    "globby": "14.0.1",
+    "parse-cmd-args": "5.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "20.12.10",
+    "tsx": "4.9.3",
+    "typescript": "5.4.5"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --import tsx --test ./src/*.test.ts",
+    "build": "rm -rf dist/ && tsc && chmod +x ./dist/bin/index.js",
+    "prepare": "npm run build"
   },
   "keywords": [
     "javascript",

package/bin/index.js

@@ -1,35 +0,0 @@
-#!/usr/bin/env node
-
-import { globby } from 'globby';
-
-import { buildFiles } from '../src/build.js';
-import { copyFiles } from '../src/copy.js';
-
-await buildFiles(
-  await globby(['**/*.mjs', '!_*/**/*', '!node_modules/', '!build/'], {
-    gitignore: true,
-    ignoreFiles: ['.onlyignore']
-  }),
-  'build/'
-);
-
-await copyFiles(
-  await globby(
-    [
-      '**/*',
-      '!**/*.mjs',
-      '!_*/**/*',
-      '!package.json',
-      '!package-lock.json',
-      '!node_modules/',
-      '!build/'
-    ],
-    {
-      gitignore: true,
-      ignoreFiles: ['.onlyignore']
-    }
-  ),
-  'build/'
-);
-
-export {};

package/src/build.js

@@ -1,27 +0,0 @@
-import { writeFile, mkdir } from 'node:fs/promises';
-import { basename, dirname, join, resolve } from 'node:path';
-
-/**
- * @param {string[]} paths
- * @param {string} buildDir
- */
-export const buildFiles = async (paths, buildDir) => {
-  await Promise.all(
-    paths.map(async path => {
-      const filename = basename(path, '.mjs');
-
-      const directory =
-        filename === 'index'
-          ? join(buildDir, dirname(path))
-          : join(buildDir, dirname(path), filename);
-
-      const html = (await import(resolve(path))).default;
-
-      if (typeof html === 'string') {
-        await mkdir(directory, { recursive: true });
-
-        await writeFile(join(directory, `index.html`), html);
-      }
-    })
-  );
-};

package/src/copy.js

@@ -1,16 +0,0 @@
-import { copyFile, mkdir } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-
-/**
- * @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));
-    })
-  );
-};

package/src/html.js

@@ -1,14 +0,0 @@
-/**
- * @param {TemplateStringsArray} strings
- * @param {any[]} values
- */
-export const html = (strings, ...values) => {
-  const processedValues = values.map(value =>
-    Array.isArray(value) ? value.join('') : value
-  );
-
-  return strings.reduce(
-    (prev, curr, i) => `${prev}${curr}${processedValues[i] || ''}`,
-    ''
-  );
-};