Use BEFORE installing Plutonium in a Rails app, running pu:core:install, or configuring initial Plutonium setup. Covers generators, gemfile, and initial config.
pu:core:install, pu:rodauth:install, pu:pkg:portal, pu:res:scaffold, pu:res:conn — never hand-write base controllers, policies, or layouts.base.rb, not plutonium.rb, for existing apps. The plutonium.rb template reruns the full bootstrap (dotenv, annotate, solid_*, assets) and clobbers git history. For any pre-existing app, use base.rb.--dest, --force, --auth, --skip-bundle for unattended runs so generators don't block on prompts. See plutonium index for the full flag matrix.plutonium (architecture overview), plutonium-auth (Rodauth setup), plutonium-portal (portal config), plutonium-create-resource (scaffolding resources).Fresh install in a new Rails app:
rails new myapp -a propshaft -j esbuild -c tailwind -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb (greenfield) OR bin/rails app:template LOCATION=.../base.rb (existing app).bundle install if you added the gem manually.rails generate pu:core:install to create base controllers, policies, definitions, and config.rails generate pu:rodauth:install + rails generate pu:rodauth:account user for auth.rails generate pu:pkg:portal admin --auth=user to create a portal.rails generate pu:res:scaffold Post title:string 'content:text?' --dest=main_app for a first resource.rails db:migrate.rails generate pu:res:conn Post --dest=admin_portal to connect the resource.config/routes.rb: mount AdminPortal::Engine, at: "/admin"./admin.Use the Rails template for a fully configured setup:
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 in one command.
⚠️ Use
base.rb, notplutonium.rb. Theplutonium.rbtemplate is forrails newonly — it re-runs the full app bootstrap (dotenv, annotate, solid_*, assets) and creates generic "initial commit" commits that clobber history. For any pre-existing app, always usebase.rb.
bin/rails app:template \
LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb
# Add to Gemfile
gem "plutonium"
# Install
bundle install
rails generate pu:core:install
After pu:core:install:
app/
├── controllers/
│ ├── plutonium_controller.rb # Base controller
│ └── resource_controller.rb # Resource CRUD base
├── definitions/
│ └── resource_definition.rb # Definition base class
├── interactions/
│ └── resource_interaction.rb # Interaction base class
├── models/
│ └── resource_record.rb # Abstract model base
├── policies/
│ └── resource_policy.rb # Policy base class
└── views/
└── layouts/
└── resource.html.erb # Base layout
config/
├── initializers/
│ └── plutonium.rb # Configuration
└── packages.rb # Package loader
packages/
└── .keep
class ResourceController < PlutoniumController
include Plutonium::Resource::Controller
# Provides: index, show, new, create, edit, update, destroy
# Plus: interactive actions, authorization, query handling
end
class ResourcePolicy < Plutonium::Resource::Policy
def create?
true # Override with your logic
end
def read?
true
end
end
class ResourceDefinition < Plutonium::Resource::Definition
# Add app-wide definition defaults here
end
class ResourceRecord < ApplicationRecord
self.abstract_class = true
# Models inherit from this for Plutonium features
end
rails generate pu:rodauth:install
# Basic user account
rails generate pu:rodauth:account user
# Admin with 2FA, lockout, audit logging
rails generate pu:rodauth:admin admin
# SaaS user with entity/organization (multi-tenant)
rails generate pu:saas:setup --user Customer --entity Organization
| Option | Description |
|---|---|
--defaults | Enable common features (login, logout, remember, reset_password) |
--kitchen_sink | Enable all available features |
--no-allow-signup | Disable public signup |
# app/controllers/resource_controller.rb
class ResourceController < PlutoniumController
include Plutonium::Resource::Controller
include Plutonium::Auth::Rodauth(:user) # Add this
end
rails generate pu:res:scaffold Post user:belongs_to title:string content:text
rails db:migrate
rails generate pu:pkg:portal admin
Select authentication when prompted:
# config/routes.rb
Rails.application.routes.draw do
mount AdminPortal::Engine, at: "/admin"
end
rails generate pu:res:conn Post --dest=admin_portal
# config/initializers/plutonium.rb
Plutonium.configure do |config|
config.load_defaults 1.0
# Custom assets (optional)
# config.assets.stylesheet = "custom_stylesheet"
# config.assets.script = "custom_script"
# config.assets.logo = "custom_logo.png"
end
Packages are loaded from config/packages.rb:
Dir.glob(File.expand_path("../packages/**/lib/engine.rb", __dir__)) { |package| load package }
Create packages in packages/ directory:
rails g pu:pkg:package blogging)rails g pu:pkg:portal admin)Install core
rails generate pu:core:install
Setup authentication (if needed)
rails generate pu:rodauth:install
rails generate pu:rodauth:account user
Create a portal
rails generate pu:pkg:portal admin
Create resources
rails generate pu:res:scaffold Post title:string content:text
Connect resources to portal
rails generate pu:res:conn Post --dest=admin_portal
Run migrations
rails db:migrate
Mount portal (add to config/routes.rb)
mount AdminPortal::Engine, at: "/admin"
Start server
rails server
For models that already exist in your app:
Include the module:
class Post < ApplicationRecord
include Plutonium::Resource::Record
end
Generate supporting files (skips model/migration):
rails g pu:res:scaffold Post
Connect to portal:
rails g pu:res:conn Post --dest=admin_portal
| Generator | Purpose |
|---|---|
pu:core:install | Initial Plutonium setup |
pu:rodauth:install | Setup Rodauth authentication |
pu:rodauth:account NAME | Create user account type |
pu:rodauth:admin NAME | Create admin account with 2FA |
pu:saas:setup | Create SaaS user + entity + membership |
pu:saas:user NAME | Create SaaS user account |
pu:saas:entity NAME | Create entity model |
pu:saas:membership | Create membership join table |
pu:pkg:package NAME | Create feature package |
pu:pkg:portal NAME | Create portal package |
pu:res:scaffold NAME | Create resource (model, policy, definition, controller) |
pu:res:conn NAME | Connect resource to portal |
pu:eject:layout | Eject layout files for customization |
pu:skills:sync | Sync Claude Code skills to project |
plutonium - Resource architecture overviewplutonium-auth - Authentication setup and configurationplutonium-package - Feature and portal packagesplutonium-portal - Portal configurationplutonium-views - Custom pages, layouts, and Phlex componentsplutonium-assets - TailwindCSS and custom stylingplutonium-create-resource - Resource scaffold optionsplutonium-portal - Portal connection