Build your own tool

A complete tool

This is not an excerpt. It is everything needed for a working page — name, inputs, and the function that does the work.

import { defineTool } from '@duckytools/sdk';

export const slugify = defineTool({
  slug: 'slugify',
  name: 'Slug Generator',
  cat: 'web',
  kind: 'text',
  blurb: 'Turn a title into a clean URL slug.',
  kw: ['slug generator', 'url slug', 'permalink'],
  opts: [
    { k: 'sep', label: 'Separator', type: 'select', def: '-',
      options: [{ v: '-', t: 'Hyphen' }, { v: '_', t: 'Underscore' }] },
  ],
  fn: (s, o) =>
    s.toLowerCase().replace(/[^a-z0-9]+/g, o.sep).replace(/^-|-$/g, ''),
});

defineTool validates and returns the object, throwing on anything that would not mount. Use validateTool instead if you would rather have { ok, errors, warnings } than an exception.

The six kinds

The kind decides what interface you get and what your function is handed. Three of them are pure, which is what makes them testable in Node with a plain assertion.

Declaring inputs

A form tool puts its inputs in fields, because for a calculator the fields are the input. Every other kind uses opts for options shown beside the main input. Both take the same shape: { k, label, type, def }.

The validator checks that a default is actually reachable — inside its own min and max, and present among a select's options. A default outside its own control is a bug that only appears when somebody resets the form, which is a bad time to find it.

Every key a tool may declare

What your function returns

Any combination of these. Anything not listed is ignored rather than an error, so a result can carry extra data of your own.

Two shorthands: a bare string means { text }, and a bare array means { results }. normalizeResult expands both if you would rather handle one shape.

Testing without a browser

import { runTool } from '@duckytools/sdk';
import assert from 'node:assert';

assert.equal(runTool(slugify, 'Hello, World!').text, 'hello-world');
assert.equal(runTool(slugify, 'A B C', { sep: '_' }).text, 'a_b_c');

runTool fills in every declared default first, so you only pass what you are varying. It refuses image, files and custom tools with an explanation rather than a confusing crash — those genuinely need a browser.

Export as one HTML file

import { toStandaloneHtml } from '@duckytools/sdk';
writeFileSync('slugify.html', toStandaloneHtml(slugify));

One file. No build step, no network, no dependencies — open it from a disk, email it, or drop it on any static host.

There is one real caveat, and the SDK enforces it rather than leaving you to find it. fn.toString() gives you the function's source, not its closure, so a tool whose body calls a helper defined beside it would serialize happily and then fail in the exported page. Export runs the function in an isolated scope first and turns that into a proper error:

Cannot export "kebab-case-converter": its `fn` calls `perLine`, which is
defined outside the function and so is not carried over. Either inline it,
or pass it in: toStandaloneHtml(tool, { deps: { perLine } }).

Standalone export covers the three pure kinds. The other three need parts of the full runtime that will not fit in a single file worth having.

The rule

Everything runs on the visitor's device. There is no upload step and no server, which is the entire point — a tool built this way cannot leak a file, because there is nowhere for the file to go.

If your idea needs a large model or a full media pipeline, it does not fit here. Saying so is better than shipping something that quietly uploads.