mix joby_kit.new (JobyKit v0.2.0)

Copy Markdown View Source

Wraps mix phx.new and replaces Phoenix's default HTML scaffolding with the JobyKit HTML layer.

Why we don't pass --no-html: that flag also removes the asset pipeline (esbuild, tailwind, watchers, Plug.Static), which we still need. We let Phoenix generate everything and then overwrite the few files the kit owns (<app>_web.ex, layouts, router, and the PageController/PageHTML modules that go away in favor of HomeLive).

Usage

mix joby_kit.new <app_name> [phx.new flags] [joby_kit flags]

Running from anywhere (Mix archive install)

Install the kit as a global Mix archive so the task works from any directory:

mix archive.install hex joby_kit

After that, from anywhere:

mix joby_kit.new my_app

The wrapper writes {:joby_kit, "~> X.Y"} into the new app's mix.exs. To use a local checkout (e.g. when developing the kit itself), pass --joby-kit-path /path/to/joby_kit to write a path dep instead.

Phoenix flags forwarded

Pass-through to mix phx.new: --database, --binary-id, --module, --app, --no-ecto, --no-mailer, --no-dashboard, --no-gettext, --verbose. The wrapper always forces --no-install (we add :joby_kit and run mix deps.get ourselves so the kit is in the dep list before the fetch).

JobyKit-specific flags

  • --joby-kit-path <path> — absolute path to a local JobyKit checkout. Writes {:joby_kit, path: "..."} into the new app's mix.exs. Useful when developing the kit itself. Defaults to detecting from the calling project's Mix.Project.deps_paths(), then falls back to a hex dep if no local checkout is found.

What the task does

  1. Shells out: mix phx.new <app_name> [forwarded flags] --no-install.
  2. Adds {:joby_kit, ...} to the new app's mix.exs (hex dep by default, path dep when --joby-kit-path is given).
  3. Runs mix deps.get inside the new app.
  4. Replaces the kit-owned HTML files:
    • lib/<app>_web.ex — JobyKit-flavored, imports JobyKit.CoreComponents.
    • lib/<app>_web/components/layouts.ex — uses JobyKit.NavComponent.simple_nav and JobyKit.CoreComponents.flash_group.
    • lib/<app>_web/components/layouts/root.html.heex.
  5. Deletes the now-redundant Phoenix scaffolding: <app>_web/components/core_components.ex, <app>_web/controllers/page_controller.ex, <app>_web/controllers/page_html.ex, and <app>_web/controllers/page_html/.
  6. Runs mix joby_kit.install (manifest, previews, design pages, AGENTS.md patches).
  7. Generates HomeLive and replaces router.ex with a JobyKit-wired version.
  8. Runs mix assets.setup and mix assets.build so priv/static/assets/ is populated before the first mix phx.server.

After this task completes:

cd <app_name>
mix phx.server

Then visit http://localhost:4000/.