gro

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

npm i -D @ryanatkn/gro

> ⚠️ I still use Gro heavily but I'm transitioning to Rust-based tooling
> with Fuz using Deno as a sidecar.
> I consider Gro deprecated but there should be a migration path.
> Please open issues if you need help.

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

Docs at gro.ryanatkn.com/docs and src/docs.

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's a dev tool, not for production use.
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
- uses Node's type stripping and supports importing JSON, SvelteKit shims,
and SSR'd Svelte files in tests/tasks/scripts
- 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 vitest
- codegen by convention with gen
- linting with ESLint
(I also maintain @feltjs/eslint-config)
- formatting with Prettier

docs

- early API docs at /docs/api
- 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 vitest
- 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:

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

It's handy to install globally too:

`bash
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:

`bash
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 the configured registry, 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 install packages to sync up
test run tests with vitest
typecheck run svelte-check or 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:

`bash
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:

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

Or programmatically:

`js
// 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.

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

`bash
gro build # build everything for production
`

Testing with vitest,
including shims for SvelteKit modules:

`bash
gro test # run all tests for *.test.ts files with vitest
gro test filepattern1 some.test another.test
gro test optional_pattern -t "optional search string for test name"
gro test -- vitest --forwarded_args 'to vitest'
`

Check all the things:

`bash
gro check # does all of the following:
gro typecheck # svelte-check with tsc fallback
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:

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

Codegen with gen:

`bash
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)

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

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

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

More:

`bash
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

`bash
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 ∙
Vitest ∙
chokidar ∙
zod ∙
@fuzdev/fuz_util ∙
ESLint ∙
Prettier ∙
svelte-check &
more

license 🐦

MIT