@feltjs/gro

gro

task runner and toolkit extending SvelteKit

limitations:

• Windows is not yet supported
• Gro has been actively used since 2019 but it has few users, so you'll likely encounter problems and undesirable limitations -- please open issues!

about

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

• task runner that uses the filesystem convention *.task.ts
  • lots of common default tasks that users can easily override and compose
• tools and patterns for developing, building, testing, deploying, and publishing SvelteKit frontends, Node servers, and libraries
  • integrated TypeScript, Svelte, and SvelteKit
  • defers to SvelteKit and Vite for the frontend and @sveltejs/package for the library
  • provides a Node loader and esbuild plugins for the server
    • supports importing TypeScript 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)
  • configurable plugins and adapters to support SvelteKit, auto-restarting Node servers, and other external build processes
    • see the Gro config docs and the default config
    • see @feltjs/felt-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
  • supports automatic type generation by convention with .schema. files using JSON Schema and json-schema-to-typescript
• linting with ESLint (we also maintain @feltjs/eslint-config)
• formatting with Prettier (it's not always pretty, but it's always consistent and it saves a lot of time)

docs

• build web frontends, servers, and libraries
  • unbundled development
  • config
  • deploy to a branch, like for GitHub pages
  • publish
• Task runner
  • tasks list
• testing with uvu
• gen code generation
• all the docs

install

depends on node >=20.5

Normally you'll want to install Gro as a dev dependency:

npm i -D @feltjs/gro

It's handy to install globally too:

npm i -g @feltjs/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 default tasks:

gro # prints available tasks - defers to the project's locally installed version of Gro

[click to see gro output in an empty project]

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

15 tasks in ./src/lib:

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
exports    writes the exports property of package.json for the lib
format     format source files
gen        run code generation scripts
lint       run eslint on the given directories and files
publish    bump version, publish to npm, and git push
test       run tests
typecheck  run tsc on the project without emitting any files
upgrade    upgrade deps

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 # print all available tasks with the pattern `*.task.ts`
gro some/dir # list all tasks inside `src/lib/some/dir`
gro some/file # run `src/lib/some/file.task.ts`
gro some/file.task.ts # same as above
gro test # run `src/lib/test.task.ts` if it exists, falling back to Gro's builtin
gro test --help # print info about the "test" task; works for every task

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:

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

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/lib/docs/deploy.md)

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

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

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

Etc:

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 src/lib/docs/task.md and src/lib/docs.

develop

npm i
npm run build # build and link `gro` - needed only once
gro build # same as `npm run build` 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 build`
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 ∙ @grogarden/util ∙ ESLint ∙ Prettier ∙ svelte-check ∙ JSON Schema ∙ json-schema-to-typescript & more

license 🐦

MIT