gro

opinionated webdev toolkit

pre-alpha: suitable only for the curious and reckless

Windows is not yet supported. WSL works well enough

heads up: For now, consider Gro's free software free as in puppy, meaning you're aware it's a lot of work to maintain, and you're inviting it into your home anyway. Docs are lacking, some things are in progress, and it might pee on your stuff. (caveat emptor: it's awwfully cute and quickly becomes a member of the family) SvelteKit and Vite are probably what you're looking for. All that out of the way: you might find some interesting or useful things here! Please open issues for questions or discussion and see contributing.md for more.

about

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

• limited but functional developing, building, testing, deploying, and publishing for Svelte/SvelteKit UIs along with Node servers, JS/TS/Svelte libraries, and other things (see the SvelteKit integration docs, the Gro config docs, and the default config)
  • fully integrated TypeScript and Svelte using esbuild in dev mode for speed
  • configurable adapters featuring e.g. optional production bundling with Rollup
  • configurable plugins to support SvelteKit, auto-restarting API servers, and other external build processes
• task runner that uses the filesystem convention *.task.ts
  • lots of common default tasks that projects can easily override and compose
• testing with uvu
• dev server with efficient caching and http2/https support
• 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
• 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
• dev server
• gen code generation
• other docs
  • log
  • options pattern
  • philosophy

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
gro # prints available tasks - defers to the project's locally installed version of Gro

usage

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 the dev server in watch mode

gro build # build everything for production

Testing with uvu:

gro test # run all tests for `*.test.ts` files with `uvu`, forwarding CLI args

Formatting with prettier:

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

gro clean # delete all build artifacts from the filesystem
gro clean --svelte --nodemodules --git # also deletes dirs and prunes git branches

gro serve # serve the current directory
gro serve some/dir and/another/dir # serve some directories

gro --version # print the Gro version

gro check # typecheck, run tests, and ensure generated files are current
gro typecheck # just the typechecking

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'

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 dev server in watch mode; it's designed as a long-running process
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

contributing

see contributing.md🌄

credits 🐢_🐢🐢

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

Gro's strategy of pairing unbundled ES modules during development with optimized bundles for production was inspired by Snowpack.

Gro's buildtime antics were inspired by Svelte.

license 🐦

MIT