Installation

For full installation reference (configuration options, base classes, what pu:core:install creates), see Reference › App. This page covers the quickest path.

New application

rails new myapp -a propshaft -j esbuild -c tailwind \
  -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb

This sets up Rails with Propshaft, esbuild, TailwindCSS, and Plutonium, plus Rodauth auth, asset pipeline, and initial migrations.

After the template completes:

cd myapp
rails db:prepare
bin/dev

Visit http://localhost:3000.

Existing application

Use base.rb, not plutonium.rb

The plutonium.rb template re-runs full app bootstrap (dotenv, annotate, solid_*, asset config) and creates generic "initial commit" commits that clobber history. For any pre-existing app, always use base.rb.

Option 1: Template

bin/rails app:template \
  LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb

Option 2: Manual

# Gemfile
gem "plutonium"

bundle install
rails generate pu:core:install

Optional: authentication

rails generate pu:rodauth:install
rails generate pu:rodauth:account user
rails db:prepare

For account options and customization, see Reference › Auth and Guides › Authentication.

Optional: assets toolchain

rails generate pu:core:assets

Installs npm packages, creates tailwind.config.js extending Plutonium's config, imports Plutonium CSS, registers Stimulus controllers (registerControllers(application), which your own JS bundle must keep), and points config.assets.stylesheet / script at your application bundles. Until then the app serves the gem's prebuilt CSS and JS, so it is required for custom CSS, brand colors or your own Stimulus controllers. It needs app/assets/stylesheets/application.tailwind.css and app/javascript/controllers/index.js (an app created with -j esbuild -c tailwind plus Stimulus). See Reference › UI › Assets and Guides › Theming.

Verify

rails runner "puts Plutonium::VERSION"

Configuration

# config/initializers/plutonium.rb
Plutonium.configure do |config|
  config.load_defaults 1.0

  # config.shell = :classic            # legacy chrome (only for upgrades)

  # Custom assets (after running pu:core:assets)
  # config.assets.stylesheet = "application"
  # config.assets.script     = "application"
  # config.assets.logo       = "custom_logo.png"
  # config.assets.favicon    = "custom_favicon.ico"
end

Full configuration options: Reference › App.

bin/dev for development

Plutonium ships a Procfile that runs Rails and the CSS watcher together:

bin/dev

Next steps

• Tutorial: build a complete blog application step-by-step
• Adding resources: create your first resource
• Creating packages: organize code into feature and portal packages