gro

task runner and toolkit extending SvelteKit 🌰 generate, run, optimize

npm i -D @ryanatkn/gro

Windows won't be supported, I chose Bash instead.

Need help or want to share thoughts? See the issues and discussions.

about

Gro is a task runner and toolkit extending SvelteKit, Vite, and esbuild for making web frontends, servers, and libraries with TypeScript. It includes:

• task runner that uses the filesystem convention *.task.ts
  • lots of common builtin tasks that users can easily override and compose
• tools and patterns for developing, building, testing, deploying, and publishing SvelteKit apps, library packages, and Node servers
  • integrated TypeScript, Svelte, and SvelteKit
  • defers to SvelteKit and Vite for the frontend and @sveltejs/package for the library
  • exposes all of its internals in $lib
  • uses Changesets for versioning and changelogs
  • provides a Node loader with a register hook
    • supports importing TypeScript, JSON, and SSR'd Svelte files in tests and tasks
    • supports SvelteKit module imports for $lib, $env, and $app in tasks, tests, Node servers, and other code outside of the SvelteKit frontend, so you can use SvelteKit patterns everywhere (these are best-effort shims, not perfect)
    • supports running TypeScript files directly without a task via gro run a.ts or node --import @ryanatkn/gro/register.js a.ts
  • configurable plugins to support SvelteKit, auto-restarting Node servers, and other external build processes
    • see the Gro config docs and the default config
    • see fuz_template for a simple starter project example, and @feltjs/felt for a more complex example with custom tasks
• testing with uvu
• codegen by convention with gen
• linting with ESLint (I also maintain @feltjs/eslint-config)
• formatting with Prettier

docs

• developing web frontends, servers, and libraries
  • config
  • dev
  • build for production
  • deploy to a branch, like for GitHub pages
  • publish to npm
• Task runner
  • builtin tasks list
• testing with uvu
• gen code generation
• public package features (nonstandard)
• full docs index

install

depends on node >=20.12

Typical usage installs @ryanatkn/gro as a dev dependency:

npm i -D @ryanatkn/gro
npx gro # note the package is namespaced, don't install `gro`

It's handy to install globally too:

npm i -g @ryanatkn/gro
gro

usage

Gro has a task runner that discovers and runs TypeScript modules with the .task. subextension. Running gro with no args prints the tasks it finds in the current directory along with its builtin tasks:

gro # prints available tasks - defers to any local gro installation

Run a task: gro [name]
View help:  gro [name] --help

19 tasks in gro:

build      build the project
changeset  call changeset with gro patterns
check      check that everything is ready to commit
clean      remove temporary dev and build files, and optionally prune git branches
commit     commit and push to a new branch
deploy     deploy to a branch
dev        start SvelteKit and other dev plugins
format     format source files
gen        run code generation scripts
lint       run eslint
publish    bump version, publish to npm, and git push
reinstall  refreshes package-lock.json with the latest and cleanest deps
release    publish and deploy
resolve    diagnostic that logs resolved filesystem info for the given input paths
run        execute a file with the loader, like `node` but works for TypeScript
sync       run `gro gen`, update `package.json`, and optionally `npm i` to sync up
test       run tests with uvu
typecheck  run tsc on the project without emitting any files
upgrade    upgrade deps

To run tasks, Gro matches your CLI input against its filesystem conventions. It tries to do the right thing, where right is helpful but not surprising, with some magic but not too much:

gro # displays all available tasks matching `src/lib/**/*.task.ts` and Gro's builtins
gro a # tries to run `src/lib/a.task.ts`, then `./a.task.ts`, then Gro's builtin if one exists
gro a --help # displays docs for the "a" task and its args, works for every task
gro some/dir # lists all tasks inside `src/lib/some/dir`
gro some/file # runs `src/lib/some/file.task.ts`
gro some/file.task.ts # same as above

Gro can also run non-task TypeScript files directly with the gro run task or register hook:

gro run foo.ts
node --import @ryanatkn/gro/register.js foo.ts

Or programmatically:

// myfile.js
import {register} from 'node:module';
register('@ryanatkn/gro/loader.js', import.meta.url);
await import('./foo.ts');

Gro has a number of builtin tasks that you can run with the CLI. To learn more see the task docs and the generated task index.

gro dev # start developing in watch mode
gro dev -- vite --port 3003 # forward args by separating sections with --

gro build # build everything for production

Testing with uvu, including shims for SvelteKit modules:

gro test # run all tests for `*.test.ts` files with `uvu`
gro test filepattern1 some.test another.test
gro test -- uvu --forwarded_args 'to uvu'

Check all the things:

gro check # does all of the following:
gro typecheck # typecheck JS/TypeScript and Svelte
gro test # run tests
gro gen --check # ensure generated files are current
gro format --check # ensure everything is formatted
gro lint # eslint

For a usage example see the check.yml CI config.

Formatting with prettier:

gro format # format all of the source files using Prettier
gro format --check # check that all source files are formatted

Codegen with gen:

gro gen # run codegen for all `*.gen.*` files
gro gen --check # error if any generated files are new or different

To deploy: (also see src/docs/deploy.md)

gro deploy # build and push to the `deploy` branch

To publish: (also see src/docs/publish.md)

gro publish # flush changeset to changelog, bump version, publish to npm, and git push

More:

gro clean # delete all build artifacts from the filesystem
gro clean --sveltekit --nodemodules --git # also deletes dirs and prunes git branches
gro upgrade excluded-dep-1 excluded-dep-2 # npm updates to the latest everything
gro --version # print the Gro version

For more see the tasks index, the task feature docs, and the docs index.

develop

npm i
npm run bootstrap # build and link `gro` without itself - needed only once
gro build # same as `npm run bootstrap` when the `gro` CLI is available
gro test # make sure everything looks good - same as `npm test`
gro test some.test another.test

# use your development version of `gro` locally in another project:
gro build # updates the `gro` CLI, same as `npm run bootstrap`
cd ../otherproject
npm link ../gro # from `otherproject/`
gro build # from `../gro` on changes

credits 🐢_🐢🐢

Gro builds on TypeScript ∙ Svelte ∙ SvelteKit ∙ Vite ∙ esbuild ∙ uvu ∙ mri ∙ chokidar ∙ zod ∙ @ryanatkn/belt ∙ ESLint ∙ Prettier ∙ svelte-check & more

license 🐦

MIT