`@davidwells/dx-args` is a forgiving argument parser for CLIs that should keep working when people type imperfect commands.

It wraps `oparser` with argv normalization, glob grouping, single-dash long-option recovery, and a predictable result shape for CLI tooling.

## Why it matters

CLI tools are more useful when they accept the way people actually type. Forgiving parsing reduces brittle command syntax and makes automation tools easier to use by humans and agents.

## README excerpt


## Install

```sh
npm install @davidwells/dx-args
```

## API

```js
const {
  dxParse,
  getGlobGroupsFromArgs,
  splitOutsideQuotes,
} = require('@davidwells/dx-args')
```

### `dxParse(argv, opts)`

Parses an argv array and returns a `ParseResult`.

```js
const result = dxParse(['--stage', 'prod', 'cool', '=', 'true'])

console.log(result.mergedOptions)
// { stage: 'prod', cool: true }
```

### `getGlobGroupsFromArgs(argv, opts)`

Extracts file and glob-like values into grouped collections.

```js
const result = getGlobGroupsFromArgs(
  ['--files', 'README.md', 'docs/**/*.md'],
  { globKeys: ['files'] }
)

console.log(result.globGroups)
// [{ key: 'files', rawKey: '--files', values: ['README.md', 'docs/**/*.md'] }]
```

### `splitOutsideQuotes(input)`

Splits a normalized option string while preserving quoted strings, objects, arrays, and `key = value` forms.

```js
splitOutsideQuotes('name = "David Wells" config={ enabled: true }')
// ['name="David Wells"', 'config={ enabled: true }']
```

## Accepted Input Forms

| Input | `mergedOptions` |
| --- | --- |
| `--stage prod` | `{ stage: 'prod' }` |
| `--stage=prod` | `{ stage: 'prod' }` |
| `stage = prod` | `{ stage: 'prod' }` |
| `stage=prod` | `{ stage: 'prod' }` |
| `-stage prod` | `{ stage: 'prod' }` |
| `-f README.md` | `{ f: 'README.md' }` |
| `--no-cache` | `{ cache: false }` |
| `--count 3` | `{ count: 3 }` |
| `--items=[1,2,3]` | `{ items: [1, 2, 3] }` |

File and glob-like values are also exposed through `globGroups`.

```js
const result = dxParse(['README.md', 'docs/**/*.md', '--stage', 'dev'])

console.log(result.globGroups)
// [{ key: '', rawKey: '', values: ['README.md', 'docs/**/*.md'] }]

console.log(result.mergedOptions)
// { stage: 'dev' }
```

## Glob Groups

`@davidwells/dx-args` groups file-looking and glob-looking arguments so CLIs can handle files separately from ordinary options.

```js
dxParse(['--files', 'README.md', 'docs/**/*.md']).globGroups
// [{ key: 'files', rawKey: '--files', values: ['README.md', 'docs/**/*.md'] }]
```

Bare file and glob values use an empty key:

```js
dxParse(['README.md', 'docs/**/*.md']).globGroups
// [{ key: '', rawKey: '', values: ['README.md', 'docs/**/*.md'] }]
```

Custom glob keys are configurable:

```js
dxParse(['--ignore', 'dist/**/*.md'], {
  globKeys: ['files', 'file', 'path', 'ignore']
}).globGroups
// [{ key: 'ignore', rawKey: '--ignore', values: ['dist/**/*.md'] }]
```

Shell-expanded file lists are intentionally not treated as leading commands:

```js
const result = dxParse(['README.md', 'NOTES.md', 'build', '=', 'false'])

console.log(result.globGroups)
// [{ key: '', rawKey: '', values: ['README.md', 'NOTES.md'] }]

console.log(result.mergedOptions)
// { build: false }
```

Values containing `node_modules/` are currently filtered from glob groups.

## Single Dash Policy

Multi-character single-dash options are treated as forgiving long options:

```js
dxParse(['-stage', 'prod']).mergedOptions
// { stage: 'prod' }
```

That also works when the value looks like a file:

```js
dxParse(['-config', 'md.config.js']).mergedOptions
// { config: 'md.config.js' }
```

Separate short flags still work:

```js
dxParse(['-l', '-a', '-h']).mergedOptions
// { l: true, a: true, h: true }
```

Short clusters are opt-in because they conflict with forgiving long option recovery:

```js
dxParse(['-abc']).mergedOptions
// { abc: true }

dxParse(['-abc'], {
  allowShortClusters: true,
  shortFlags: ['a', 'b', 'c']
}).mergedOptions
// { a: true, b: true, c: true }
```


## Links

- [Package source](https://github.com/DavidWells/markdown-magic/tree/master/packages/dx-args)
- [npm package](https://www.npmjs.com/package/@davidwells/dx-args)

Forgiving argv parser for CLIs that accepts loose key/value syntax, globs, and typo-tolerant long flags.

@davidwells/dx-args


`@davidwells/extract-deps` extracts imports, requires, and exports from JavaScript and TypeScript source without building a full AST.

It is useful for tooling that needs a fast, practical view of dependency relationships: build systems, CI change detection, documentation tools, and agent workflows that need to understand code structure.

## Why it matters

Developer tools often need enough code awareness to make good decisions without paying the cost or complexity of a full compiler pass. This package captures that middle ground.

## Links

- [npm package](https://www.npmjs.com/package/@davidwells/extract-deps)

Dependency extraction utility for finding imports, requires, and exports in JavaScript and TypeScript code without AST parsing.

@davidwells/extract-deps


`@davidwells/wait-for` is a polling utility for waiting on asynchronous systems with configurable retry logic, timeouts, cancellation, callbacks, and backoff.

It came from real integration work where transient failures and eventual consistency made one-off retry code hard to maintain.

## Why it matters

Distributed systems often need to wait for something to become true: a service comes online, a device finishes provisioning, a queue drains, or an API becomes consistent. This package makes those waits explicit and reusable.

## Links

- [Package source](https://github.com/DavidWells/packages/tree/master/packages/wait-for)
- [npm package](https://www.npmjs.com/package/@davidwells/wait-for)
- [Related post](/blog/powerful-polling-with-waitfor)

Flexible polling and retry utility for waiting on async systems with cancellation, backoff, callbacks, and timeouts.

@davidwells/wait-for


Analytics is an open-source analytics abstraction layer for tracking page views, custom events, and identified users across multiple providers.

It grew out of years of instrumenting product telemetry across different companies and teams. The project includes the core library plus an ecosystem of plugins and integrations for routing events to different destinations without rewriting application code.

## Why it matters

Product telemetry should be portable, testable, and understandable. Analytics gives teams a small event API while keeping provider-specific details in plugins.

## Links

- [Docs site](https://getanalytics.io)
- [GitHub repository](https://github.com/DavidWells/analytics)
- [npm package](https://www.npmjs.com/package/analytics)

Lightweight analytics abstraction for page views, custom events, identify calls, and provider plugins.

Analytics

Configorama adds variable support to configuration files so environment-specific values can be composed without turning every config into custom JavaScript.

It is the kind of utility that comes from building repeatable systems: keep the config readable, make the dynamic parts explicit, and let the same structure work across local, staging, and production environments.

## Why it matters

Infrastructure, deployment, and application config tends to drift when values are copied by hand. Variable-aware config keeps those moving parts easier to reuse and easier to review.

## README excerpt


## Key Features

- **Multiple file formats** - yml, yaml, json, toml, ini, hcl (Terraform), TypeScript, JavaScript, markdown
- **Rich variable sources** - env vars, CLI flags, file refs, git data, cron expressions, eval/if expressions
- **Async/sync function execution** - Import and execute JavaScript/TypeScript files with argument passing
- **Self-referencing** - Reference other values within the same config using dot notation
- **Custom variable sources** - Pluggable architecture to add your own variable resolvers
- **Filters and functions** - Transform and combine values with built-in or custom operators
- **Metadata extraction** - Analyze configs without resolving them, or get full resolution history
- **Circular dependency detection** - Helpful error messages instead of infinite loops
- **TypeScript support** - Full type definitions and TypeScript file execution via tsx/ts-node

## Getting Started

### Installation

**As a library dependency:**

```bash
npm install configorama
```

**As a global CLI tool:**

```bash
npm install -g configorama
```

### Quick Start

**Async API (recommended for most use cases):**

```javascript
const path = require('path')
const configorama = require('configorama')
const cliFlags = require('minimist')(process.argv.slice(2))

// Path to yaml/json/toml config
const myConfigFilePath = path.join(__dirname, 'config.yml')

// Execute config resolution asynchronously
const config = await configorama(myConfigFilePath, { options: cliFlags })

console.log(config) // resolved config
```

**Sync API (for synchronous execution contexts):**

```javascript
const path = require('path')
const configorama = require('configorama')
const cliFlags = require('minimist')(process.argv.slice(2))

// Path to yaml/json/toml config
const myConfigFilePath = path.join(__dirname, 'config.yml')

// Execute config resolution synchronously
const config = configorama.sync(myConfigFilePath, { options: cliFlags })

console.log(config) // resolved config
```

**Example configuration file (`config.yml`):**

```yaml
# Environment variable
apiKey: ${env:API_KEY}

# CLI option (e.g., --stage prod)
environment: ${opt:stage, 'dev'}

# Self-reference to other values
service: my-app
fullName: ${service}-api

# File reference
secrets: ${file(./secrets.yml)}

# Git information
branch: ${git:branch}
commit: ${git:sha1}

# Conditional logic
memorySize: ${if(${environment} === 'prod' ? 1024 : 512)}

# Nested references
database:
  host: ${env:DB_HOST, 'localhost'}
  port: ${env:DB_PORT, 5432}
  name: ${service}-${environment}
```

### Running Examples

The project includes example files demonstrating various features:

```bash
# Clone the repository
git clone https://github.com/DavidWells/configorama
cd configorama

# Install dependencies
npm install

# Run async API example
node examples/using-async-api.js --stage prod

# Run sync API example
node examples/using-sync-api.js --stage dev

# Run zero-config example
node examples/zero-config.js

# Run TypeScript example
node examples/typescript/using-typescript.js
```

---


## Links

- [GitHub repository](https://github.com/DavidWells/configorama)
- [npm package](https://www.npmjs.com/package/configorama)

Configuration loader with variable interpolation for making config files reusable across environments.

Configorama


Idempotent Requests is a demo of retry-safe API behavior across client and server boundaries.

It explores how idempotency keys help systems handle retries without accidentally duplicating work.

## Why it matters

Modern APIs are surrounded by retries: browsers retry, infrastructure retries, clients retry, and users retry. Idempotency turns that uncertainty into an explicit protocol.

## Links

- [GitHub repository](https://github.com/DavidWells/spike-idempotent-requests)
- [Demo](https://demo-idempotent-requests.netlify.app)
- [Related post](/blog/building-idempotent-apis-with-aws-lambda-powertools)

Demo showing retry-safe request flows on the client and server with idempotency keys.

Idempotent Requests Demo


Markdown Magic uses hidden comment blocks inside markdown files to transform, inject, and synchronize content from local files, remote sources, and custom transforms.

It is the kind of tool that turns documentation upkeep into a repeatable workflow instead of a manual copy/paste chore.

## Why it matters

Docs go stale when source material is duplicated. Markdown Magic keeps the markdown file readable while letting generated sections stay connected to their real source of truth.

## Links

- [GitHub repository](https://github.com/DavidWells/markdown-magic)
- [npm package](https://www.npmjs.com/package/markdown-magic)
- [Portfolio entry](/work/markdown-magic)

Markdown automation tool that keeps docs, README sections, code examples, and generated content in sync.

Markdown Magic


`@davidwells/box-logger` creates formatted terminal boxes, headers, horizontal lines, and multi-column layouts for CLI output.

It is small UI infrastructure for command-line tools: make important output easier to scan without forcing every script to rebuild terminal formatting from scratch.

## Why it matters

Readable terminal output changes how quickly people can understand a tool. Clear headers, status boxes, and dividers make CLI workflows easier to debug, document, and reuse.

## What it includes

- Boxes with configurable borders, padding, alignment, colors, and width constraints.
- Header helpers for success, error, warning, and info output.
- Horizontal rules with optional labels.
- Stacked and horizontal box layouts.
- Dynamic and async content functions that receive layout width.
- ASCII fallbacks and multiple border styles for different terminal environments.

## Install

```bash
npm install @davidwells/box-logger
```

## Example

```javascript
const { makeBox, logHeader } = require('@davidwells/box-logger')

logHeader.success('Deploy complete')

console.log(makeBox({
  title: 'Build summary',
  content: 'All packages passed',
  borderStyle: 'rounded',
  borderColor: 'green'
}))
```

## Links

- [npm package](https://www.npmjs.com/package/@davidwells/box-logger)

Terminal formatting utility for boxes, headers, dividers, and structured CLI output.

@davidwells/box-logger


`@davidwells/glob-utils` is a file discovery helper for projects that need to locate files with glob patterns, regular expressions, ignore rules, and gitignore-aware filtering.

It is small infrastructure for larger automation systems: find the relevant files, avoid noise, and feed a cleaner file set into the next step.

## Why it matters

Build tools, documentation generators, and CI utilities all start with file discovery. Making that layer reusable keeps later tooling simpler.

## Links

- [Package source](https://github.com/DavidWells/packages/tree/master/packages/util-globs)

File discovery utility that accepts glob strings and regular expressions for flexible project scanning.

@davidwells/glob-utils


`@davidwells/lerna-smart-run` is a monorepo workflow helper for running npm scripts against packages that changed since a previous branch-based tag.

It wraps ordinary Lerna commands with sequencing controls, tagging behavior, and options for running specific packages first or last.

## Why it matters

Large repositories get slow when every task runs everywhere. Smarter package selection keeps CI focused while preserving the ordering rules that real deployment pipelines need.

## Links

- [npm package](https://www.npmjs.com/package/@davidwells/lerna-smart-run)

Lerna workflow utility for running package scripts only where changes require them.

@davidwells/lerna-smart-run


`@davidwells/md-utils` is a collection of markdown helpers used by documentation and content automation workflows.

It sits next to Markdown Magic as lower-level markdown plumbing: small parsing and string utilities that make markdown documents easier to inspect and transform.

## Why it matters

Markdown becomes infrastructure once docs, READMEs, examples, and site content need to stay connected. Small utilities make those workflows easier to build without copying parsing logic everywhere.

## Links

- [Package source](https://github.com/DavidWells/packages/tree/master/packages/util-md)
- [npm package](https://www.npmjs.com/package/@davidwells/md-utils)

Small markdown utility package for parsing and transforming markdown content.

@davidwells/md-utils

`@davidwells/parse-time` turns loose human time input into JavaScript `Date` objects.

It handles practical strings like `in 2 hours`, `tomorrow at noon`, `next friday`, `3 days ago`, direct timestamps, and normal date objects.

## Why it matters

Developer tools and workflow automation often need to accept human-friendly time input without making users memorize strict timestamp formats.

## README excerpt


## Installation

```bash
npm install @davidwells/parse-time
```

## Usage

```javascript
const { parseTime } = require('@davidwells/parse-time');

// Parse specific dates and times
const date1 = parseTime('January 15th 2024 at 3:30pm');
console.log(date1.toISOString()); // 2024-01-15T15:30:00.000Z

// Parse relative times
const now = new Date('2023-01-01T12:00:00Z');
const date2 = parseTime('in 2 hours', { now });
console.log(date2.toISOString()); // 2023-01-01T14:00:00.000Z

// Parse special keywords
const date3 = parseTime('today at 5pm', { now });
console.log(date3.toISOString()); // 2023-01-01T17:00:00.000Z

// Parse "never" (returns far future date)
const never = parseTime('never');
console.log(never.toISOString()); // 9999-12-31T00:00:00.000Z

// Parse "now" (returns current time)
const currentTime = parseTime('now');
console.log(currentTime.toISOString()); // Current time in ISO format

// Parse unix timestamp
const timestamp = 1672574400; // 2023-01-01T12:00:00Z
const date4 = parseTime(timestamp);
console.log(date4.toISOString()); // 2023-01-01T12:00:00.000Z

// Parse Date object
const dateObj = new Date('2023-05-15T10:30:00Z');
const date5 = parseTime(dateObj);
console.log(date5.toISOString()); // 2023-05-15T10:30:00.000Z
```

## Supported Formats

The library supports a wide variety of time formats:

- **Specific dates and times**: `January 15th 2024 at 3:30pm`, `Dec 25 2023 midnight`, `July 4 2023 noon`
- **Relative times**: `in 2 hours`, `3 days ago`, `next week`, `next month`
- **Special keywords**: `today at 5pm`, `yesterday noon`, `tomorrow at midnight`
- **Time of day**: `11am`, `11pm`, `12:30am`, `12:30pm`
- **Days of the week**: `this friday`, `next monday`, `last tuesday`
- **Specific dates**: `oct 22nd 1987`, `3pm oct 22nd 1987`, `the 22nd of october, 1987 at 7pm`
- **Holidays**: `4th of july`, `9pm on the 4th of july`
- **Relative periods**: `in 12 minutes`, `in 2 hours`, `in 31 hours`, `in 20 hours 40 minutes`
- **Decimal periods**: `in 20.2h`, `in 1.5 weeks`
- **Longer periods**: `in 5 weeks`, `in 2 years`, `in 2 years and 5 weeks`
- **Past periods**: `2 days ago`, `2 days and 6 hours ago`, `1 month ago`, `14 days ago`
- **ISO format**: `2015-10-31`, `2015-10-31 20:30`, `2015-10-31 8:30pm`


## Links

- [Package source](https://github.com/DavidWells/components/tree/master/packages/parse-time)
- [npm package](https://www.npmjs.com/package/@davidwells/parse-time)

Parser for turning messy human time strings into JavaScript Date objects.

@davidwells/parse-time


`@davidwells/smart-log` is a logging layer for command-line tools and automation scripts.

It supports normal user-facing logs, debug namespaces, JSON output for programmatic callers, silent mode, and log dumping for later inspection.

## Why it matters

Good CLI tools need to be useful for humans and machines. The same command may need readable terminal output for a developer, structured JSON for another tool, or a complete debug log for a failing automation run.

## What it includes

- Debug namespaces controlled by `DEBUG` or `--debug`.
- `--silent` mode for quiet automation.
- `--json` output for downstream tools and agents.
- Log dumping with ANSI-stripped or raw output.
- Runtime toggles for silent, JSON, and debug behavior.
- Optional console patching so existing `console.log` calls route through the same policy.

## Install

```bash
npm install @davidwells/smart-log
```

## Example

```javascript
const { _console, debug, setJson } = require('@davidwells/smart-log')

const logHttp = debug('app:http')

_console.log('Starting job')
logHttp('request received')

setJson(true)
_console.json({ ok: true }, 'Result')
```

## Links

- [npm package](https://www.npmjs.com/package/@davidwells/smart-log)

Logging utility for CLIs with debug namespaces, JSON mode, silent mode, and log dumping.

@davidwells/smart-log


Devtools Utilities is a grouped entry for smaller CLI and workflow packages that support local development, monorepo automation, package orchestration, and command execution.

These utilities are better shown as a family than as a dozen tiny cards. The point is the pattern: repeated development workflows become reusable packages instead of one-off scripts.

## Why it matters

Developer productivity work compounds when common operations become tools. Listing packages, installing dependencies, finding binaries, generating types, running commands, ordering package builds, and coordinating tasks are all small pieces of a larger automation system.

## Utility areas

- CLI command execution and process orchestration.
- Type generation for JavaScript and TypeScript projects.
- Monorepo package listing, install orchestration, and build ordering.
- Task running across packages and workflows.
- Binary discovery and graceful process exits.
- Terminal logging and formatting through `@davidwells/smart-log` and `@davidwells/box-logger`.

## Included packages

| Package | Purpose | Status |
|---|---|---|
| `@davidwells/cli-typegen` | Generate types for a project. | local / unreleased |
| `@davidwells/package-build-order` | Compute package build order in a workspace. | local / unreleased |
| `@davidwells/task-runner` | Run tasks in parallel or sequence. | local / unreleased |
| `@davidwells/packages-list` | List packages in a directory. | local / unreleased |
| `@davidwells/packages-installer` | Detect package managers and install dependencies. | local / unreleased |
| `@davidwells/cli-runner` | Run CLI commands from reusable code. | local / unreleased |
| `@davidwells/get-bin-path` | Resolve paths to binaries. | local / unreleased |
| `@davidwells/graceful-exit` | Standardize graceful Node.js exits. | public package |
| `@davidwells/wifi-utils` | Utility helpers for local network workflows. | public package |

## Related project pages

- [@davidwells/extract-deps](/projects/extract-deps)
- [@davidwells/lerna-smart-run](/projects/lerna-smart-run)
- [@davidwells/smart-log](/projects/smart-log)
- [@davidwells/box-logger](/projects/box-logger)

A grouped set of CLI, monorepo, package-management, and workflow utilities for automating local development.

Devtools Utilities

`git-er-done` wraps common git-diff workflows into a JavaScript API for tooling that needs to understand what changed.

It is useful for CI scripts, release tooling, docs automation, monorepo checks, and any workflow that needs to react to modified, created, or deleted files.

## Why it matters

Change detection is the foundation for smarter automation. Once a tool can answer what changed, it can decide what to test, build, document, publish, or skip.

## README excerpt


## Install

```bash
npm install git-er-done
```

### Basic Usage

```js
const { gitDetails } = require('git-er-done')

// Git commit ref / branch to check against. Default is 'master'
const GIT_COMMIT_REF = '9f63b23ec99e36a176d73909fc67a39dc3bd56b7'

gitDetails({
  base: GIT_COMMIT_REF,
  // Optional: specify working directory (defaults to process.cwd())
  // cwd: '/path/to/repo'
}).then((git) => {
  /* git data returns
  {
    fileMatch: [Function], <-- Lookup function
    modifiedFiles: [ Array of modified files ],
    createdFiles: [ Array of created files ],
    deletedFiles: [ Array of deleted files ],
    commits: [ Array of commits ],
    lastCommit: { Object with last commit info },
    linesOfCode: [AsyncFunction: linesOfCode],
    dir: String path to git repo
  }
  */

  if (git.modifiedFiles.length) {
    // Some files have changed
  }

  if (git.createdFiles.length) {
    // Some files have been created
  }

  if (git.deletedFiles.length) {
    // Some files have been deleted
  }
})
```

### Getting Lines of Code Changed

```js
const { gitDetails } = require('git-er-done')

const git = await gitDetails({
  base: 'main',
  head: 'feature-branch'
})

const totalLines = await git.linesOfCode()
console.log(`Total lines changed: ${totalLines}`)
```

### Using fileMatch with Patterns

Use glob patterns to match specific files. You can also use negation patterns:

```js
const { gitDetails } = require('git-er-done')

const git = await gitDetails({ base: 'main' })

// Simple pattern matching
const srcCode = git.fileMatch('src/**/*.js')
/* srcCode returns object with:
{
  modified: Boolean,
  modifiedFiles: Array,
  created: Boolean,
  createdFiles: Array,
  deleted: Boolean,
  deletedFiles: Array,
  edited: Boolean,
  editedFiles: Array
}
*/

if (srcCode.edited) {
  console.log('Source code has been edited')
  console.log('Modified files:', srcCode.modifiedFiles)
  console.log('Created files:', srcCode.createdFiles)
}

// Match with negation - find all JSON files except package.json
const jsonFiles = git.fileMatch('**/**.json', '!**/package.json')
if (jsonFiles.modified) {
  console.log('Non-package JSON files modified:', jsonFiles.modifiedFiles)
}
if (jsonFiles.created) {
  console.log('Non-package JSON files created:', jsonFiles.createdFiles)
}

// Check markdown files
const mdFiles = git.fileMatch('**/*.md')
if (mdFiles.edited) {
  // Do stuff because markdown files are changed
  console.log('All markdown changes:', mdFiles.editedFiles)
}
```


## Links

- [Package source](https://github.com/DavidWells/components/tree/master/packages/util-git-info)
- [npm package](https://www.npmjs.com/package/git-er-done)

Git change detection utility for finding modified, created, and deleted files since a commit or branch.

git-er-done


Icon Pipeline is a build tool for optimizing SVG icons and producing SVG sprites.

It is a focused example of developer experience work: take a repetitive frontend asset workflow and turn it into a reliable pipeline.

## Why it matters

Design systems and product UIs need icon workflows that are easy to run, review, and reuse. This project packages that pipeline as a tool.

## Links

- [GitHub repository](https://github.com/DavidWells/icon-pipeline)
- [Demo](https://icon-pipeline.netlify.app)

SVG icon build pipeline for optimizing icon sets and generating sprites for product interfaces.

Icon Pipeline

This spike explores using AWS LLRT as a faster JavaScript runtime for Lambda functions.

It pairs a working repository with a writeup so the runtime tradeoffs are easier to test and understand.

The implementation details below are synced from the project README.


This project demonstrates how to build a serverless API using AWS Lambda with [LLRT (Low Latency Runtime)](https://github.com/awslabs/llrt) - a lightweight JavaScript runtime optimized for AWS Lambda.

The function are behind simple HTTP API Gateway endpoints.

## Features

- Fast cold starts with LLRT runtime
- Multiple API endpoints (/hello and /goodbye)
- ARM64 architecture for better performance/cost ratio
- Custom Serverless Framework plugin for deployment validation
- Automated LLRT bootstrap setup
- **🔧 LLRT Compatibility Checker** - Verify code compatibility before deployment

## Prerequisites

- Node.js 18 or later
- AWS CLI configured with appropriate credentials
- Serverless Framework CLI (`npm install -g serverless`)

## Quick Start

1. Clone the repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Set up LLRT bootstrap:
   ```bash
   npm run setup
   ```
4. Test LLRT compatibility (optional):
   ```bash
   npm run check:hello
   npm run check:goodbye
   # Or run all tests
   npm test
   ```
5. Deploy to AWS:
   ```bash
   npm run deploy
   ```

## API Endpoints

### Hello Endpoint

- **URL**: GET /hello
- **Query Parameters**: 
  - `name` (optional) - Name to greet
- **Example Response**:
  ```json
  {
    "message": "Hello World from LLRT!",
    "timestamp": "2024-03-14T12:00:00.000Z",
    "path": "/hello",
    "method": "GET"
  }
  ```

### Goodbye Endpoint

- **URL**: GET /goodbye
- **Query Parameters**: 
  - `name` (optional) - Name to bid farewell
- **Example Response**:
  ```json
  {
    "message": "Goodbye World, thanks for using LLRT!",
    "timestamp": "2024-03-14T12:00:00.000Z",
    "path": "/goodbye",
    "method": "GET"
  }
  ```

## Project Structure

```bash
.
├── bootstrap # LLRT runtime
├── bin/ # CLI tools
│   └── llrt-check.js # LLRT compatibility checker
├── docs/ # Documentation
│   └── llrt-check.md # Checker documentation
├── node_modules # Node.js dependencies
├── package.json
├── serverless.yml
├── src/ # Source code
│   ├── hello.js
│   ├── goodbye.js
│   └── test-function.js
├── scripts/ # Setup and utility scripts
│   ├── setup.js
│   ├── get-compat.js
│   └── test-checker.js
└── llrt-compatibility.json # Compatibility matrix
```

## Deployment

To deploy the service, run:

```bash
npm run deploy
```

## Cleanup

To delete the service, run:

```bash
npm run remove
```

## LLRT Compatibility Checker

This project includes a custom compatibility checker to verify your code will work with LLRT before deployment:

```bash
# Check specific functions
npm run check:hello
npm run check:goodbye

# Check any JavaScript file
./bin/llrt-check.js path/to/your/function.js

# Run all compatibility tests
npm test
```

The checker performs:
- **Static Analysis**: Scans for unsupported modules and features
- **Runtime Testing**: Executes code in both Node.js and LLRT environments
- **Performance Comparison**: Reports execution time differences

See [docs/llrt-check.md](docs/llrt-check.md) for detailed usage instructions.

## Notes

- You can deploy LLRT in many ways, see https://github.com/awslabs/llrt?tab=readme-ov-file#configure-lambda-functions-to-use-llrt
- See [Serverless Framework docs](https://www.serverless.com/framework/docs) for more information on how to deploy and manage your service.

## Performance results

You can perf test with `node perf-test.js`

Average response time: 54.05ms. Not too shabby.

```bash
=== PERFORMANCE COMPARISON SUMMARY ===
Comparing Node.js vs LLRT implementations:

Hello Function:
  Average: 149.96ms (Node) vs 32.37ms (LLRT) - 78.4% faster
  Min: 127.19ms (Node) vs 22.47ms (LLRT) - 82.3% faster
  Max: 182.75ms (Node) vs 51.00ms (LLRT) - 72.1% faster

Goodbye Function:
  Average: 133.00ms (Node) vs 30.40ms (LLRT) - 77.1% faster
  Min: 119.05ms (Node) vs 22.92ms (LLRT) - 80.7% faster
  Max: 148.67ms (Node) vs 48.12ms (LLRT) - 67.6% faster

Test Function:
  Average: 135.46ms (Node) vs 30.98ms (LLRT) - 77.1% faster
  Min: 124.46ms (Node) vs 21.34ms (LLRT) - 82.9% faster
  Max: 151.80ms (Node) vs 49.26ms (LLRT) - 67.6% faster

=== OVERALL SUMMARY ===
LLRT is on average 77.6% faster than Node.js
Average response times: 139.47ms (Node) vs 31.25ms (LLRT)
```

Example of using the AWS LLRT JavaScript runtime with Serverless Framework.

LLRT Lambda Runtime Spike


`persist-previous-build-assets` copies previous build artifacts into the latest deployment so users with older HTML do not hit missing hashed JavaScript or CSS chunks.

It targets a practical production failure mode: a new deploy ships, old chunk URLs disappear, and active users see chunk-loading errors.

## Why it matters

Reliability work is often small glue code around the edges of deployment. Preserving previous assets gives frontend applications a safer deploy path without requiring a larger infrastructure rewrite.

## Links

- [Package source](https://github.com/DavidWells/packages/tree/master/packages/util-persist-previous-build-assets)
- [npm package](https://www.npmjs.com/package/persist-previous-build-assets)

Build utility that carries previous hashed assets into the latest deployment to reduce stale chunk failures.

persist-previous-build-assets


React Component Primitives is a grouped family of reusable components and utilities: `Flex`, `Form`, `Icon`, `Input`, `Select`, `react-dom-primitives`, and supporting tooling.

Instead of presenting each small component as its own project, this entry captures the design-system layer as a reusable package family.

## Why it matters

Product teams move faster when common interface building blocks are consistent, documented, and reusable. These packages are part of that reusable frontend foundation.

## Links

- [Component source](https://github.com/DavidWells/packages/tree/master/components)

Reusable React component primitives for forms, layout, icons, inputs, selects, and DOM building blocks.

React Component Primitives


`safe-await` is a tiny helper for making async control flow easier to read.

Instead of wrapping every awaited call in its own try/catch block, it returns a tuple-style result that makes the success and error paths explicit.

## Why it matters

Small utilities like this reduce repeated code and make common JavaScript patterns easier to reuse consistently across projects.

## Links

- [GitHub repository](https://github.com/DavidWells/safe-await)
- [npm package](https://www.npmjs.com/package/safe-await)

Small JavaScript utility for working with async/await without wrapping every call in repetitive try/catch blocks.

safe-await


This example shows how to run pure ESM functions on AWS Lambda with Serverless Framework without adding a bundling step.

It is a small proof that not every serverless project needs a build pipeline to be understandable and deployable.

## Why it matters

Removing unnecessary build steps can make functions easier to inspect, debug, and ship.

## Links

- [GitHub repository](https://github.com/DavidWells/serverless-esm-functions-no-build-example)
- [Related post](/blog/using-unbundled-esm-in-aws-lambda)

Example project showing pure ESM AWS Lambda functions with Serverless Framework and no bundling step.

Serverless ESM Functions with No Build Step


Style Guard is a small DX package family for catching missing CSS Module class references during development.

The runtime package wraps CSS Module objects with a proxy, while the Babel plugin can apply that guard automatically in development builds.

## Why it matters

CSS Module regressions are easy to miss when a class name is removed or renamed. Style Guard turns those mistakes into immediate development errors instead of quiet UI breakage.

## Links

- [Runtime package](https://www.npmjs.com/package/style-guard)
- [Babel plugin](https://www.npmjs.com/package/babel-plugin-style-guard)
- [Runtime source](https://github.com/DavidWells/packages/tree/master/packages/style-guard)

CSS Modules safety tooling that throws in development when code references missing class names.

Style Guard


Types with JSDoc is a set of examples showing how JavaScript projects can get strong editor support and type checking without converting every file to TypeScript.

It matches the way this site is built: JavaScript with `checkJs`, JSDoc annotations, and generated types where they help.

## Why it matters

Typed JavaScript is a practical middle ground for existing codebases. It improves tooling and correctness while keeping the authoring model lightweight.

## Links

- [GitHub repository](https://github.com/DavidWells/types-with-jsdocs)

Practical examples for getting TypeScript-style type checking in JavaScript projects through JSDoc.

David Wells

Builder of things

Software architect
& product wrangler

Projects

Featured packages and tools