Use this skill whenever starting a new tutorial project, understanding the end-to-end
workflow from scaffold to deployment, or customizing the rails-app template's built-in
features. Trigger on: 'new tutorial', 'create tutorial', 'getting started',
'npx create-tutorialkit-rb', 'scaffold', 'first lesson', 'deploy tutorial', 'build:wasm',
'COEP/COOP headers', 'hosting setup', 'CSS classes', 'design system', 'application.css',
'rails-app template', 'branding', 'logo', 'favicon', 'accent color', or asking how to
set up, build, style, brand, or deploy a Rails tutorial from scratch. Provides exact CLI
commands, project structure, WASM build steps, the rails-app CSS design system, branding
customization, deployment header configuration, and troubleshooting. Do NOT attempt
project setup or deployment without this skill. Do NOT use for frontmatter reference
(use tutorial-lesson-config) or WASM compatibility (use rails-wasm-author-constraints).
Use this skill whenever starting a new tutorial project, understanding the end-to-end
workflow from scaffold to deployment, or customizing the rails-app template's built-in
features. Trigger on: 'new tutorial', 'create tutorial', 'getting started',
'npx create-tutorialkit-rb', 'scaffold', 'first lesson', 'deploy tutorial', 'build:wasm',
'COEP/COOP headers', 'hosting setup', 'CSS classes', 'design system', 'application.css',
'rails-app template', 'branding', 'logo', 'favicon', 'accent color', or asking how to
set up, build, style, brand, or deploy a Rails tutorial from scratch. Provides exact CLI
commands, project structure, WASM build steps, the rails-app CSS design system, branding
customization, deployment header configuration, and troubleshooting. Do NOT attempt
project setup or deployment without this skill. Do NOT use for frontmatter reference
(use tutorial-lesson-config) or WASM compatibility (use rails-wasm-author-constraints).
Tutorial Quickstart
End-to-end guide: scaffold a project, write your first lesson, and deploy.
Step 1: Scaffold
npx create-tutorialkit-rb my-tutorial
The CLI prompts for:
Prompt
Default
Notes
Tutorial name
random (e.g., "fierce-turtle")
Used as package.json name
Directory
./{name}
Where files are created
Hosting provider
Skip
Netlify or Fly.io — adds COEP/COOP headers (and a Dockerfile + deploy workflow for Fly.io)
Package manager
npm
npm, yarn, pnpm, or bun
Init git repo?
Yes
Creates initial commit
Edit Gemfile?
Yes
Opens ruby-wasm/Gemfile in $EDITOR
Skip all prompts with --defaults, or pass flags directly:
npm run pack:wasm # ~1-4 minutes; downloads a prebuilt Ruby base binary on first run
Host prerequisites: Ruby 3.3.x with RubyGems >= 3.6 and < 4 (gem update --system 3.6.9), a Rust toolchain, and the gh CLI — the script preflights these and tells you what to fix. npm run build:wasm is the slow legacy fallback (5-20 min) if the fast path fails.
Step 3: Start the Dev Server
npm run dev # Starts at http://localhost:4321/
The sample tutorial loads immediately. You'll see the starter lessons from the scaffold.
# _files/workspace/app/controllers/pages_controller.rbclassPagesController < ApplicationController# Add your action hereend
4e. Add Solution Files
Put the completed code in _solution/:
# _solution/workspace/app/controllers/pages_controller.rbclassPagesController < ApplicationControllerdefhome
render plain:"Hello from Rails on WebAssembly!"endend
4f. Delete the Sample Content
Remove the scaffold's starter lessons once you have your own:
The scaffold includes a pre-built rails-app template at src/templates/rails-app/ with a minimal Rails app skeleton and CSS design system. Most tutorials should extend this template rather than building from scratch.
What's Included
CSS design system — modern BEM-based stylesheet with CSS custom properties
Layout — nav bar with brand name; flash messages; .container wrapper
The template is intentionally minimal. Tutorial-specific features like authentication, models, controllers, and views should be added via lesson _files/ overlays or custom templates that extend rails-app.
CSS Design System
The template's application.css uses pure CSS with custom properties and BEM naming. Use these classes in your lesson ERB files — no extra setup needed.
Then reference it from your lesson's _files/.tk-config.json:
{"extends":"../../../../../templates/my-app"}
See the rails-file-management skill for details on template inheritance.
Step 6: Deploy
Tutorials need Cross-Origin-Embedder-Policy and Cross-Origin-Opener-Policy headers for WebContainers to work. If you chose a hosting provider during scaffold, these are already configured.
Build for Production
npm run build # Produces a static site in dist/
Manual Header Configuration
If you didn't choose a provider during scaffold, add these headers to every response:
To match your tutorial's branding to your project's documentation site, update these files:
Logos
Replace public/logo.svg (light mode) and public/logo-dark.svg (dark mode) with your project's logo SVG. Use a dark fill (e.g., #0F4D8A) for the light-mode version and a light fill (e.g., #E4E6E9) for the dark-mode version.
Title in Top Bar
Edit src/components/TopBar.astro — add a <span> after the logo images inside the <a> tag:
<spanclass="ml-2 text-sm font-medium text-tk-elements-topBar-iconButton-iconColor whitespace-nowrap">
Your Tutorial Title
</span>
Favicon
Replace public/favicon.svg with your project's icon. Optionally add a public/favicon.ico for broader browser support.
Accent Colors (UnoCSS Theme)
Override the accent palette in uno.config.ts to change buttons, links, active tabs, and badges site-wide:
Generate your scale from your brand's primary color. The 600 slot is the main brand color; 500 is for hover/interactive states; 400 is used in dark mode.
Component Hardcoded Colors
Some components use hardcoded Tailwind color classes instead of theme tokens. Search for and replace these:
src/components/HelpDropdown.tsx — Reload button uses bg-blue-600. Change to bg-accent-600 hover:bg-accent-700.
src/components/HeadTags.astro — Rails path link colors. Update hex values to match your brand.
Rails Demo App CSS
Update the primary color in src/templates/rails-app/workspace/app/assets/stylesheets/application.css:
:root {
--color-primary: #0F4D8A; /* your brand color */--color-primary-hover: #0C3F72; /* darker shade */--color-primary-light: #EFF6FF; /* tinted background */
}
GitHub Link
Update the repo URL in src/components/GitHubLink.astro:
