onlybuild 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+## Reporting Issues
+
+If you have found a bug in `onlybuild` please consider the following when submitting an issue:
+
+- **Search existing [GitHub Issues](https://github.com/neogeek/onlybuild/issues)** - The bug you are experiencing might have already been reported or even fixed in an unreleased version of `onlybuild` so be sure to review both [open](https://github.com/neogeek/onlybuild/issues?state=open) and [closed](https://github.com/neogeek/onlybuild/issues?state=closed) issues.
+- **Create a reproducible test case** - To make it easier for maintainers to validate the issue please include a [gist](https://gist.github.com/) containing files used to reproduce the issue.
+- **Include relevant information** - Include clear steps to reproduce the issue.
+
+## Pull Requests
+
+Before submitting a pull request, be sure that the following requirements are met:
+
+- Additional tests have been added to validate the changes.
+- Relevant documentation has been added.
+- The build passes.
+
+## Code Style
+
+Make sure to install and enable the [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) plugin in VS Code.
+
+## License
+
+By contributing to `onlybuild` you agree that your contributions fall under the same license, [The MIT License (MIT)](./LICENSE).

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Scott Doxey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# onlybuild
+
+> A zero-config cli for building static websites.
+
+[![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)
+[![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)
+
+## Features
+
+- 🪄 Can be used without installing it via `npx onlybuild`
+- 🐣 Small footprint when installed
+- ⏱️ Fast build times, [see benchmark data](#Benchmark)
+- 🧰 Use with any framework or no framework at all
+- 📦 Easily deploy built files to any static file service, ex: Google Cloud Bucket, AWS S3, GitHub Pages
+- 📖 Easily import data from local JSON files or fetch remote API data
+
+## Social
+
+- Star [this repo on GitHub](https://github.com/neogeek/onlybuild) for updates
+- Follow me on [Bluesky](https://bsky.app/profile/scottdoxey.com) or [Twitter](https://twitter.com/neogeek)
+- Join the [Discord](https://discord.gg/nNtFsfd)
+- Follow me on [GitHub](https://github.com/neogeek/)
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start Guide](#quick-start-guide)
+- [Getting Started](#getting-started)
+- [File Structure](#file-structure)
+- [Ignore Files](#ignore-files)
+- [Formatting Files](#formatting-files)
+- [Examples](#examples)
+- [Benchmark](#benchmark)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [Community Roadmap](#community-roadmap)
+- [License](#license)
+
+## Install
+
+### Globally
+
+```bash
+$ npm install onlybuild -g
+```
+
+```bash
+$ onlybuild
+```
+
+### NPX
+
+```bash
+$ npx onlybuild
+```
+
+### Local
+
+```bash
+$ npm install onlybuild --save-dev
+```
+
+```json
+{
+  ...
+  "scripts": {
+    "build": "onlybuild"
+  },
+  ...
+}
+```
+
+```bash
+$ npm run build
+```
+
+## Quick Start Guide
+
+Create a new file `index.mjs` with the following contents:
+
+```javascript
+export default '<h1>Hello, world!</h1>';
+```
+
+Run `npx onlybuild` from the directory the `index.mjs` file is in.
+
+That's it! You will now have a `build/` directory with an `index.html` file in it.
+
+## Getting Started
+
+### Simple Example
+
+You can have the default export return a string.
+
+```javascript
+export default '<h1>Hello, world!</h1>';
+```
+
+### Method Example
+
+You can have the default export generate a string at runtime via a method.
+
+```javascript
+const renderPage = () => '<h1>Hello, world!</h1>';
+
+export default renderPage();
+```
+
+### Asynchronous Example
+
+You can return asynchronously if you need to read a local file or call an external API.
+
+```javascript
+import { readFile } from 'node:fs/promises';
+
+const renderPage = async () => await readFile('index.html', 'utf8');
+
+export default renderPage();
+```
+
+```javascript
+const comments = await fetch(
+  'https://jsonplaceholder.typicode.com/posts/1/comments'
+).then(response => response.json());
+
+export default `<div>${comments
+  .map(post => `<section><h2>${comments.name}</h2><p>${post.body}</section>`)
+  .join('\n')}</div>`;
+```
+
+### Parse Markdown
+
+You can run the contents through other libraries, for example, converting a Markdown file into HTML before returning it using libraries like [Marked](https://github.com/markedjs/marked).
+
+```javascript
+import { readFile } from 'node:fs/promises';
+
+import { marked } from 'marked';
+
+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.
+
+```javascript
+import { html } from 'onlybuild';
+
+export default html`<h1>Hello, world!</h1>`;
+```
+
+Install the [lit-html](https://marketplace.visualstudio.com/items?itemName=bierner.lit-html) plugin in VS Code to help format the HTML on save.
+
+## 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.
+
+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`.
+
+## 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.
+
+```
+*.md
+
+screenshot.png
+
+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.
+
+```bash
+$ 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"
+```
+
+## Examples
+
+1. [Hello, world!](./examples/hello-world/) - A simple Hello, world example.
+1. [Markdown](./examples/markdown/) - Get the contents of a local Markdown file and convert the contents to HTML.
+1. [External API](./examples/external-api/) - Output data fetched from an external API.
+1. [<code>&#96;html&#96;</code> String Template](./examples/html-string-template/) - Use the <code>&#96;html&#96;</code> string template utility to add syntax highlighting to HTML.
+1. [Includes](./examples/includes/) - An example that uses reusable includes for building multiple pages.
+
+## 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.
+
+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` |
+| [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` |
+| [Gatsby](https://www.gatsbyjs.com/) 4.19.0-cli | `14.462` | `15.722` | `17.967` | `22.356` | `29.059` |
+
+See more benchmark data at <https://www.zachleat.com/web/build-benchmark/>
+
+To run the benchmarks locally you have to install `bc`. This can be done on macOS by using `brew install bc`.
+
+Once you have `bc` installed, install NPM packages for the main repo, then navigate to the `tests/benchmarks` directory, install NPM packages there as well, and then run `./bin/run.sh` to start the benchmark tests.
+
+## Testing
+
+Run all tests via `npm test`.
+
+- Tests are authored using the native [Node.js test runner](https://nodejs.org/api/test.html).
+- Tests are run automatically via GitHub Actions on each new PR.
+- For you add a new feature or fix a bug, please include the benchmark output in the PR along with your device stats.
+
+## Contributing
+
+Be sure to review the [Contributing Guidelines](./CONTRIBUTING.md) before logging an issue or making a pull request.
+
+## Community Roadmap
+
+The goal of this project is to keep the features it offers to a minimum, allowing you, the developer, to forge your own path. If you have feature requests or bugs, please create an issue and tag them with the appropriate tag. If an issue already exists, vote for it with 👍.
+
+- [Feature Requests](https://github.com/neogeek/onlybuild/labels/enhancement)
+- [Bugs](https://github.com/neogeek/onlybuild/labels/bug)
+
+## License
+
+[The MIT License (MIT)](./LICENSE)

package/bin/index.js

@@ -0,0 +1,35 @@
+#!/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/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "onlybuild",
+  "description": "A zero-config cli for building static websites.",
+  "version": "1.0.0",
+  "engines": {
+    "node": ">=20.x"
+  },
+  "type": "module",
+  "bin": {
+    "onlybuild": "./bin/index.js"
+  },
+  "main": "./src/index.js",
+  "license": "MIT",
+  "dependencies": {
+    "globby": "14.0.1"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "javascript",
+    "build",
+    "static"
+  ],
+  "authors": [
+    {
+      "name": "Scott Doxey",
+      "email": "hello@scottdoxey.com",
+      "homepage": "http://scottdoxey.com/"
+    }
+  ],
+  "homepage": "https://github.com/neogeek/onlybuild",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/neogeek/onlybuild.git"
+  }
+}

package/src/build.js

@@ -0,0 +1,27 @@
+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

@@ -0,0 +1,16 @@
+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

@@ -0,0 +1,14 @@
+/**
+ * @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/src/index.js

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