@feltcoop/gro

gro

opinionated webdev toolkit 🌰

limitations:

• Windows is not yet supported
• SvelteKit and Vite integration is incomplete
• Gro is actively used but has few users, so you'll likely find problems and undesirable limitations -- please open issues! or contact us directly
  • example: there are definitely things that should be configurable that aren't
  • gro wants all source code and assets to be in src/ or node_modules/, which may annoy
  • please open issues with questions, bugs, thoughts, etc

about

Gro is an opinionated webdev toolkit that complements SvelteKit and Vite for making web frontends, servers, and libraries. It includes:

• limited but functional developing, building, testing, deploying, and publishing for Svelte/SvelteKit apps along with Node servers, JS/TS/Svelte libraries, and other things
  • integrated TypeScript, Svelte, and SvelteKit
  • see the SvelteKit integration docs, the Gro config docs, and the default config
  • configurable plugins and adapters to support SvelteKit, auto-restarting API servers, and other external build processes - ideally would use SvelteKit/Vite instead
  • example usage in a starter project: @feltcoop/felt-template
• task runner that uses the filesystem convention *.task.ts
  • lots of common default tasks that projects can easily override and compose
• testing with uvu
• codegen by convention with gen
  • includes automatic type generation using JSON Schema and json-schema-to-typescript
• integrated platform-independent fs (code is parameterized with an fs argument)
  • modeled & implemented with fs-extra, a drop-in replacement for Node's fs with better semantics
  • memory implementation works everywhere JS runs
  • TODO more, like: localStorage, GitHub repo, generic keyvalue stores, a composition/proxy API
• linting with ESLint (we also maintain @feltcoop/eslint-config)
• formatting with Prettier: it's not always pretty, but it's always formatted
• more to come, exploring what deeply integrated tools enable for developer power, ergonomics, and productivity

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 >= 16.6

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

npm i -D @feltcoop/gro

It's handy to install globally too:

npm i -g @feltcoop/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

14 tasks in gro/src:

build      build the project
cert       creates a self-signed cert for https with openssl
check      check that everything is ready to commit
clean      remove temporary dev and build files, and optionally prune git branches
deploy     deploy to a branch
dev        start SvelteKit and other dev plugins
format     format source files
gen        run code generation scripts
help       alias for `gro` with no task name provided
lint       run eslint on the source files
publish    bump version, publish to npm, and git push
test       run tests
typecheck  typecheck 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 help # same as `gro`
gro --help # same as `gro`
gro some/dir # list all tasks inside `src/some/dir`
gro some/file # run `src/some/file.task.ts`
gro some/file.task.ts # same as above
gro test # run `src/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 filepatternB
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/docs/deploy.md)

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

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

gro publish patch # bump version, publish to npm, and git push
gro publish major --and args --are forwarded --to 'npm version'

Etc:

gro clean # delete all build artifacts from the filesystem
gro clean --sveltekit --nodemodules --git # also deletes dirs and prunes git branches
gro cert # uses openssl to create a self-signed certificate for local https testing
gro upgrade excluded-dep-1 excluded-dep-2 # npm updates to the latest everything

gro --version # print the Gro version

For more see src/docs/task.md and src/docs.

develop

npm i
npm run bootstrap # build and link `gro` - needed only once
gro test # make sure everything looks good - same as `npm test`

# development
gro dev # start SvelteKit and other plugins, like API servers; usually you'll keep this running
gro build # update the `gro` CLI locally

# use your development version of `gro` locally in another project
cd ../otherproject
npm link ../gro

# release
gro build # build for release and update the `gro` CLI

credits 🐢_🐢🐢

Gro builds on TypeScript ∙ Svelte ∙ SvelteKit ∙ Vite ∙ esbuild ∙ uvu ∙ mri ∙ fs-extra ∙ @feltcoop/util ∙ ESLint ∙ Prettier ∙ svelte-check ∙ JSON Schema ∙ json-schema-to-typescript & more

license 🐦

public domain ⚘ The Unlicense