# `mix joby_kit.new`
[🔗](https://github.com/jobycorp/joby_kit/blob/v0.2.0/lib/mix/tasks/joby_kit.new.ex#L1)

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/`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*