diff --git a/astro.config.mjs b/astro.config.mjs index 3822a44..760155b 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -89,6 +89,20 @@ export default defineConfig({ }, { label: "Guides", autogenerate: { directory: "clack/guides" } }, ], + }, + { + label: "Args", + id: "args", + icon: "seti:shell", + link: "/args/getting-started", + items: [ + { label: "Basics", link: "/args/getting-started" }, + { + label: "API", + link: "args/api", + }, + { label: "Guides", autogenerate: { directory: "args/guides" } }, + ], } ]), ], diff --git a/package.json b/package.json index f0502d8..803608a 100644 --- a/package.json +++ b/package.json @@ -11,6 +11,7 @@ }, "dependencies": { "@astrojs/starlight": "^0.32.2", + "@bomb.sh/args": "^0.3.1", "@clack/core": "^0.4.1", "@clack/prompts": "^0.10.0", "@types/node": "^22.13.11", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b61c78f..d79f914 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -11,6 +11,9 @@ importers: '@astrojs/starlight': specifier: ^0.32.2 version: 0.32.4(astro@5.5.4(@types/node@22.13.11)(rollup@4.36.0)(typescript@5.8.2)) + '@bomb.sh/args': + specifier: ^0.3.1 + version: 0.3.1 '@clack/core': specifier: ^0.4.1 version: 0.4.1 @@ -87,6 +90,9 @@ packages: resolution: {integrity: sha512-emqcG3vHrpxUKTrxcblR36dcrcoRDvKmnL/dCL6ZsHaShW80qxCAcNhzQZrpeM765VzEos+xOi4s+r4IXzTwdQ==} engines: {node: '>=6.9.0'} + '@bomb.sh/args@0.3.1': + resolution: {integrity: sha512-CwxKrfgcorUPP6KfYD59aRdBYWBTsfsxT+GmoLVnKo5Tmyoqbpo0UNcjngRMyU+6tiPbd18RuIYxhgAn44wU/Q==} + '@clack/core@0.4.1': resolution: {integrity: sha512-Pxhij4UXg8KSr7rPek6Zowm+5M22rbd2g1nfojHJkxp5YkFqiZ2+YLEM/XGVIzvGOcM0nqjIFxrpDwWRZYWYjA==} @@ -1891,6 +1897,8 @@ snapshots: '@babel/helper-string-parser': 7.25.9 '@babel/helper-validator-identifier': 7.25.9 + '@bomb.sh/args@0.3.1': {} + '@clack/core@0.4.1': dependencies: picocolors: 1.1.1 diff --git a/src/content/docs/args/api.mdx b/src/content/docs/args/api.mdx new file mode 100644 index 0000000..e406846 --- /dev/null +++ b/src/content/docs/args/api.mdx @@ -0,0 +1,4 @@ +--- +title: Args +description: Learn about the Args package and its capabilities +--- diff --git a/src/content/docs/args/getting-started.mdx b/src/content/docs/args/getting-started.mdx new file mode 100644 index 0000000..622da8d --- /dev/null +++ b/src/content/docs/args/getting-started.mdx @@ -0,0 +1,95 @@ +--- +title: Getting Started +description: Learn how to get started with Args +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +A <1kB library for parsing CLI flags. Inspired by Deno's `std/cli` [`parseArgs`](https://github.com/denoland/std/blob/main/cli/parse_args.ts) module. + +## Features + +🤏 very small + +🍃 very simple + +🏃 very fast (beats [`node:util`](https://nodejs.org/api/util.html#utilparseargsconfig)) + +🔏 strongly typed + +## Installation + +You can install Args using npm, yarn, or pnpm: + + + + ```bash + npm install @bomb.sh/args + ``` + + + ```bash + pnpm add @bomb.sh/args + ``` + + + ```bash + yarn add @bomb.sh/args + ``` + + + + +## Quick Start + +Basic usage does not require any configuration. + +```ts twoslash +import { parse } from "@bomb.sh/args"; + +// my-cli build --bundle -rf --a value --b=value --c 1 +const argv = process.argv.slice(2); +const args = parse(argv); + +console.log(args); +// { _: ['build'], bundle: true, r: true, f: true, a: "value", b: "value", c: 1 } +``` + +Parsing can be configured to ensure arguments are coerced to specific types, which enhances type safety. + +```ts twoslash +import { parse } from "@bomb.sh/args"; + +const args = parse(process.argv, { + default: { a: 1, b: 2, c: "value" }, + alias: { h: "help" }, + boolean: ["foo", "bar"], + string: ["baz", "qux"], + array: ["input"], +}); +``` + +## Benchmarks + +``` +mri x 1,650,986 ops/sec ±0.32% (97 runs sampled) +@bomb.sh/args x 1,407,191 ops/sec ±0.38% (99 runs sampled) +minimist x 383,506 ops/sec ±0.28% (99 runs sampled) +node:util x 320,953 ops/sec ±0.35% (98 runs sampled) +yargs-parser x 31,874 ops/sec ±1.32% (92 runs sampled) +``` + +## Acknowledgements + +This package was previously published as `ultraflag` up until `v0.3.0`, when it was renamed to `@bomb.sh/args`. + +## Next Steps + +1. Check out our [Examples](/docs/args/guides/examples) for more practical use cases +2. Learn about [Best Practices](/docs/args/guides/best-practices) for building CLIs +3. Explore the [API Reference](/docs/args/api) for detailed documentation +4. Join our [Discord community](https://bomb.sh/chat) for support and discussions + +## Contributing + +We welcome contributions! Please check out our [Contributing Guide](/contributing) for details on our code of conduct and the process for submitting pull requests. diff --git a/src/content/docs/args/guides/best-practices.mdx b/src/content/docs/args/guides/best-practices.mdx new file mode 100644 index 0000000..108867b --- /dev/null +++ b/src/content/docs/args/guides/best-practices.mdx @@ -0,0 +1,18 @@ +--- +title: Best Practices +description: Learn the best practices for using Args effectively +--- + +This guide covers recommended practices and patterns for using Args effectively in your applications. + +## General Guidelines + +_TBD_ + +## Performance Considerations + +_TBD_ + +## Accessibility + +_TBD_ diff --git a/src/content/docs/args/guides/examples.mdx b/src/content/docs/args/guides/examples.mdx new file mode 100644 index 0000000..b605b58 --- /dev/null +++ b/src/content/docs/args/guides/examples.mdx @@ -0,0 +1,14 @@ +--- +title: Examples +description: Learn through practical examples of using Args +--- + +This guide provides practical examples of using Args in different scenarios. + +## Basic Examples + +_TBD_ + +## Advanced Examples + +_TBD_