joby_kit.new

Generates a new Phoenix application with JobyKit wired in from the first commit.

mix archive.install hex joby_kit_new
mix joby_kit.new my_app
cd my_app
mix phx.server

Why this is a separate package

joby_kit.new has to run before a project exists, so it can only be a Mix archive. Everything else the kit provides — mix joby_kit.install, joby_kit.bootstrap, joby_kit.gen.wrapper, joby_kit.lint — runs inside a project that already has :joby_kit as a dependency.

Shipping all of them in one archive meant two copies of those tasks existed on any machine with the archive installed: the global one and the project's. The global one answered, so an app's mix.exs did not control which JobyKit generated its files — whichever archive was on the machine did. In practice that produced apps scaffolded from a version nobody had pinned, and template fixes that silently never reached anyone.

Splitting removes the possibility rather than detecting it. This package contains the project generator and nothing else, so it has nothing to shadow. It is the same arrangement Phoenix uses: phx_new is a separate hex package from phoenix.

For the same reason this package has no :joby_kit dependency. It writes {:joby_kit, "~> X.Y"} into the generated mix.exs and then shells out to mix joby_kit.install inside the new app, so the scaffolding comes from the kit version that app just pinned.

What it does

mix phx.new <app> --no-install (plus any forwarded flags).
Adds {:joby_kit, "~> X.Y"} to the new app's mix.exs.
mix deps.get.
Replaces the kit-owned HTML layer: <app>_web.ex, layouts.ex, and root.html.heex — including Phoenix's pre-paint theme script, so light/dark switching works out of the box.
Deletes the Phoenix scaffolding the kit supersedes (core_components.ex, PageController, PageHTML).
Runs mix joby_kit.install in the new app — manifest, previews, /design and /custom-designs pages, AGENTS.md and CLAUDE.md.
Generates HomeLive and a JobyKit-wired router.ex.
mix assets.setup && mix assets.build, so the first mix phx.server serves real CSS instead of 404ing.

Flags

Forwarded to phx.new: --database, --binary-id, --module, --app, --no-ecto, --no-mailer, --no-dashboard, --no-gettext, --verbose. --no-install is always forced, because :joby_kit has to be in the dep list before the fetch.

Generator-specific:

--joby-kit-path <path> — write a path dep instead of a hex dep, for working on the kit itself.

Versioning

The kit release this generator targets is a literal in Mix.Tasks.JobyKit.New (@joby_kit_version), bumped alongside a kit release — the same way phx.new tracks phoenix. It is not read from a loaded :joby_kit, because there deliberately isn't one.

License

MIT.