Jumpstart Pro

poetry-jumpstart_pro re-skins a Jumpstart Pro app with Poetry: one generator installs Poetry recreations of the app's screens, from sign in to billing to the admin dashboard, and wires what they need.

How it works

Jumpstart Pro serves its interface from an engine inside the app. Rails looks for a view in the app's own app/views before it looks in an engine, so a file there replaces the engine's view of the same path. The installer copies Poetry recreations into app/views, written against the same routes, instance variables, locals and translation keys as the screens they replace.

The gem ships only Poetry views, never Jumpstart Pro's source, and your licensed Jumpstart code is never touched. Every installed file is yours to edit, and deleting one falls back to Jumpstart's view.

Before you install

The app runs Jumpstart Pro on Rails 8 authentication, with its sign in screens under users/. An app still on Devise is not covered.
The development database exists and is migrated. The generator runs poetry:install, which loads the app to build its safelist, and Jumpstart's admin resources read the database as they load.
Your work is committed, so the installer's changes read as one diff: it adds views and a helper, and edits five stylesheets, the Madmin initializer and three test files.

Install

Add the gem beside the umbrella, run the generator, then rebuild the stylesheet and check the result. The generator installs Poetry first when the app does not have it yet.

gem "poetry"
gem "poetry-jumpstart_pro", group: :development

bundle install
bin/rails db:prepare
bin/rails generate poetry_jumpstart_pro:install
bin/rails tailwindcss:build
bin/rails poetry:check

Name categories to install part of the app. Running it again is safe: files that already match are skipped, and every other step checks before it changes anything.

bin/rails generate poetry_jumpstart_pro:install auth shell

Category	Screens
`auth`	sign in, the two-factor challenge, sign up, the profile, password reset, sudo, the OAuth buttons and form errors
`shell`	the navbar and its Hotwire Native variant, the account, user and development menus, notifications, flash messages and the footer
`accounts`	accounts and teams, members, invitations, transfers, the account password and the settings navigation
`users`	the mention chip, agreements, connected accounts, referrals and two-factor backup codes
`api_tokens`	the token list, detail and forms, with usage examples in code blocks
`notifications`	the notifications page, the navbar panel and the row
`announcements`	the announcements list, the announcement and the row
`checkouts`	the checkout page
`public`	the landing, about, privacy and terms pages
`dashboard`	the signed-in home
`errors`	the 404, 500 and generic error pages
`billing`	billing, charges, subscriptions and their changes, payment methods and pricing
`madmin`	the admin dashboard and the array field

What else the installer changes

Stylesheets. Jumpstart's stylesheet declares a few things for the whole page that would win over Poetry's tokens and components. The forms plugin moves to its class strategy, the primary color and page background come from Poetry's tokens, the global link and list rules go, and the heading, code and kbd rules skip Poetry's components.
A helper. app/helpers/poetry_jumpstart_pro_helper.rb draws Jumpstart's pagination as the pagination component and maps its toasts onto Poetry's toast variants.
The admin. Madmin's pages load the app stylesheet, so the dashboard and the array field render styled.
Tests. Jumpstart's own sign in, two-factor and pagination tests get selectors that match the Poetry markup.
Default views. In development, Jumpstart copies a few of its views into the app on boot. A copy you never edited is replaced without a prompt; an edited one asks first, like any generator conflict.

--skip-stylesheets, --skip-tests and --skip-poetry-install leave those steps out, and --theme picks the theme when Poetry is installed for the first time.

Customizing the screens

The installed views are yours. Edit them as you would any view; the components inside are Poetry's, each documented under Components, and bin/rails poetry:check verifies the markup you compose. A run of the installer never overwrites a file you edited without asking: files that match are skipped, Jumpstart's untouched default copies are replaced, and anything else is a generator conflict you answer.

bin/rails generate poetry_jumpstart_pro:install --pretend   # what would change
bin/rails generate poetry_jumpstart_pro:install --skip      # keep every file you have
bin/rails generate poetry_jumpstart_pro:install --force     # take the gem's version of each

To restore one screen to the gem's version, delete it and run the installer for its category. To go back to Jumpstart's own screen, delete the override.

Upgrading

The gem releases with the rest of Poetry, so one bundle update moves both. Run the installer again to take the new versions of the screens; the conflicts it reports are the files you changed.

bundle update poetry poetry-jumpstart_pro
bin/rails generate poetry_jumpstart_pro:install
bin/rails tailwindcss:build
bin/rails test && bin/rails test:system

When a Jumpstart Pro update changes a screen, your override keeps rendering in its place. Compare the engine views the update touched, under lib/jumpstart/app/views, with your overrides of the same paths, and run the suite.

Your tests

Jumpstart's own suite runs against the Poetry screens. The installer updates the selectors that asserted on the replaced markup: the sign in helpers click any element named commit, because a Poetry submit is a button rather than an input, and the pagination test reads Poetry's navigation landmark. --skip-tests leaves them as they are. For new system tests, Poetry::Ui::Testing drives Poetry's controls the way a user does; the Testing guide has it.

Troubleshooting

The screens look unstyled. Rebuild the stylesheet, with bin/rails tailwindcss:build or bin/dev: the new views and Poetry's safelist are new sources for it.
poetry:install stops with a database error. Create and migrate the development database, then run the installer again.
A screen still looks like Jumpstart's. It is one of the views that stay Jumpstart's, or you kept your own copy at a conflict.
Dark mode. It follows Jumpstart's theme setting: the color theme in the profile puts the dark class on the page, and Poetry's tokens follow it.
The admin pages are unstyled. Check that config/initializers/madmin.rb has the Madmin.stylesheets line the madmin category adds, and restart the server.

Removing it

Delete the installed views and app/helpers/poetry_jumpstart_pro_helper.rb, revert the installer's stylesheet, initializer and test edits from version control, and remove the gem. Jumpstart's own screens are back as soon as the overrides are gone.