Developing your app

Look at you, you already have a beautiful working project! Everything is wired and configured. And it's even live on the internet for other people to see and interact with! You've deployed your app and have something live before even starting development, isn't that beautiful?

Now it's just a matter of building your own business on top of the template.

To begin development, just run:

bin/dev

And the local development server will start up, serving everything needed for you to see your project in localhost (at port 3000 by default) -- just visit http://localhost:3000

Start coding or vibe coding

RailsFast comes ready for you to vibe code on top of it.

It ships with smart context rules so that Cursor, Claude Code, Codex etc. can easily understand the structure and contents of the project, and can use the right tools in the appropriate subparts of the project. It understands the technologies used, where they're used, and how to fetch detailed docs, so vibe coding on top of it should be a breeze. Just ask Claude Code or Cursor whatever you want to do.

For example, let's ask AI to create a new "Help" page for us, wire it with the appropriate routes and controllers, add it to the navigation bar and footer, and fill it with useful help content from the FAQ.

Your first vibe coded feature

To get started, we could just ask AI something like:

create a new demo "Help" page, add it to the navbar and footer, use the FAQ component as main content, add a title and description and SEO meta tags too

Let the AI agent browse through your project and create + edit the necessary files. When it's done, it should have done something similar to this:

• Added a new route to the config/routes.rb file
• Created a new view under app/views/demo/help.html.erb (or similar) and filled it with content
• Added the controller action to app/controllers/demo_controller.rb
• Edited the navbar and footer partials at app/views/layouts/partials/_navbar.html.erb (and footer)

Now if you visit and reload your project at http://localhost:3000, you'll see the new Help page in the navbar and footer, and you should be able to navigate to it if you click on it.

Your second vibe coded thing

Another idea would be to ask AI to edit the default landing page and make it yours. AI can replace the placeholder text and generate landing copy text specific to your project, so you can just move really quick to put something out there. I would ask the AI agent something like:

my startup idea is: [describe it]. With this info, please edit @app/views/demo/landing_page.html.erb to replace the placeholder text and tailor the landing page to my startup idea. Use any components under @app/views/components/railsfast. There's no need to use all components, nor any need to keep any of the existing components. No need to keep any of the placeholder content: edit, delete, and mix the available UI components as needed. Just tailor the landing page to the idea in the best way possible

Of course, the resulting AI-generated text will be pretty bland, and will look placeholder too. I strongly recommend against this approach for your actual project landing page: for the long-term you'll need an actually well-researched, well-thought-out, well-written landing page for your startup, with your actual product images. But for demo purposes I think this is a really quick way to get started: all of a sudden you can have a fully branded landing page, tailored to your specific product offering, ready in theory to start charging money.

You get the hang of it -- so go ahead and start building!

Add the Context7 MCP

One of the most important, if not the most imporant thing you can do when vibe coding is give the AI good context. Context about your app, context about your architecture, context about the APIs and dependencies you're using. RailsFast ships with already good context by default, but to make it work you need to connect to the Context7 MCP: a service that will help your AI get updated docs about any of the APIs and dependencies your project is using.

To do that, first grab your free Context7 API key, and then configure your AI to use it:

For example, if you're using Claude Code just run:

claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "YOUR_API_KEY"

If you're using Cursor or other IDEs, you can learn how to install it on the Context7 GitHub page.

Do small, incremental steps

Don't try to vibe code your whole project at once! Break big milestones into extremely simple tasks that the AI can achieve without problem. Maybe have the AI edit 1-2 files at the time, at most!

Commit often to GitHub. Don't wait until you have 20 or 30 edited files to commit! Do very small, incremental steps, test them, and commit the changes to GitHub before moving on to the next thing.

Deploy often!

Your main goal while developing should be to press the deploy button as much and as often as possible:

kamal deploy

Here's the workflow: ask AI one tiny thing, review the code and verify everything works, commit and hit kamal deploy. Rinse and repeat.

How your RailsFast project is structured

For development (no matter if you're coding manually, reviewing AI-generated code or managing AI agents), you'll need to have a rough notion of where things are.

If you're already familiar with Rails, you already know this. If you're new to Rails, this is what your RailsFast project (and every other Rails project) is structured like:

• Front-end
  • Views:
    • All visible pages ("HTML") are called views
    • Views live under app/views
    • Rails uses erb for views. erb is just HTML with Ruby code. It's somewhat similar to what PHP code looks like.
    • If a view file name starts with underscore (_), it's called a partial. Example: _navbar.html.erb. Partials are like components, you can include and reuse them in other views.
  • Controllers:
    • Every view (except partials) needs a corresponding controller
    • A controller is just what sits between your backend/database and your views
    • The controller fetches data and gets your views ready for display
    • Controllers live under app/controllers
    • The name of the controller needs to match the name of the folder the view is in
      • Example: demo -- If your view is app/views/demo/help.html.erb, the corresponding controller needs to be app/controllers/demo_controller.rb (note how the demo part is identical in both file names)
    • The controller needs to define a controller action (a method inside the controller file) whose name needs to match the name of the view file
      • If your view is help.html.erb, inside your controller you need to define the help method
      • You can define special "@ variables" in your controller action. If a variable name inside your controller action starts with @, you can use it right away in the corresponding view without doing anything else. Use this to, for example, load data and display it in the view.
  • Interactive pages and JavaScript
    • Rails comes with a suite of tools called Hotwire to make your pages interactive (not just static)
      • For interactive pages, Rails uses Hotwire Turbo: a way of modifying / deleting / adding HTML to your pages in a few lines of Ruby code, without needing any JavaScript.
      • If you do need JavaScript, Rails uses Hotwire Stimulus by default. Stimulus controllers let you add JS functionality to your views with the minimal amount of JavaScript needed.
    • You can also add React, Vue, Svelte, or any other JS framework / library to your Rails project. I do not recommend this, though, I believe you'll find both Turbo and Stimulus work way better when used within a Rails project than any JS framework
    • To add any JS library to your Rails project, use importmaps
      • For example, if you want to use Three.js in your project, just run bin/importmap pin three and Three.js will be available to use in your Stimulus controllers
• Back-end
  • Models
    • In Rails, you don't interact with your SQL database directly
    • Database tables are abstracted into models (using something called ActiveRecord)
    • A model is just a database table abstraction + related logic
    • Models live under app/models
      • Example: if you have a user table in your database, the corresponding model is User and lives under app/models/user.rb
    • Most of the logic in your entire project should live in the models ("heavy models, thin controllers")
    • Models can be interacted within Rails like User.last, or User.last.created_at
    • Models can (and should) validate data and enforce lengths, limits, etc.
    • Models can define relationships between other models (like has_many, belongs_to... which map to DB relationships)
    • You can still write SQL queries in Rails, but it's usually easier to just use model methods provided like ActiveRecord
      • For example: User.last.posts.count joins the post table with the user table and gets you the post count for the last user
  • Database
    • PostgreSQL
      • PostgreSQL (sometimes called psql or postgres) is the database of choice in RailsFast
      • PostgreSQL is robust, it's the industry standard, and it scales beautifully
      • It has very powerful plugins to do things like vector embeddings for AI, or geolocation things, etc.
      • PostgreSQL has pretty much everything you startup will ever need, even if you reach millions of users
      • Since you don't really interact with the database directly in Rails, you can in theory swap PostgreSQL for any other database like MySQL, SQLite, MariaDB, etc. This is NOT recommended in practice, but just know that it's in theory possible
    • Migrations
      • You never touch the database directly
      • You alter the state of the database through database migrations
      • Migrations live under db/migrate
      • Migrations define changes in the database, like new tables or fields, new relationships, new indices, or deletions
      • You generate a new migration with rails g migration
      • You run pending migrations with rails db:migrate
      • The current state of your database after all migrations is always available in db/schema.rb
      • You never touch the database directly (again, worth repeating, because if you do you'll be bypassing all model validations and callbacks and your database may get to inconsistent states. You do everything through migrations and through ActiveRecord model logic)
  • Services / POROs
    • Some logic may not belong to any specific model, and it may not belong to any view/controller either
    • For that kind of logic, using services is usually a good idea
    • A service is just a PORO (Plain Old Ruby Object): that is, a default Ruby file without any required Rails logic
    • Services live under app/services
    • Example of services: a thin wrapper over an API you're using (like openai_service.rb), codebase-wide utilities, etc.
  • Background / async jobs
    • Background jobs go in app/jobs
    • You can set scheduled, recurring jobs (cron-like) by editing config/recurring.yml
    • Background jobs work thanks to a component of Rails called solid_queue
• Config
  • Routes
    • Your routes are defined in config/routes.rb
    • The routes file just link specific routes like /help to the corresponding controller action
    • You can do all sorts of things with routes: conditionals for auth / logged in users, dynamic routes by matching params, etc.
  • Deployments
    • We use Kamal for deployments
    • Everything related to your deployments (servers, domain name, etc.) is configured in the config/deploy.yml file
  • Environments
    • Advanced configuration for your app can be found at config/application.rb
    • Environment-specific overrides can be made at config/environments/development.rb, config/environments/production.rb, etc.
    • None of this is needed to get you started, everything has been already configured in RailsFast, just know that these files exist
  • Gem-specific configs
    • Under the config folder you'll usually find configuration files for gems (gems are software packages in Ruby, like libraries)

This is just a quick overview of what a Rails project looks like so you can get up to speed fast. It is by no means a comprehensive list of everything Rails has, I just wanted to give you the right mental models to get you to 80% understanding in a few minutes. If you want to go in depth, I recommend reading the official Rails guides for getting started with Rails, or better yet: asking ChatGPT/Grok any questions you may have.

Convention over configuration

A tip before I send you off: when I started programming on Ruby on Rails, I remember feeling many things worked "like magic". There's many things in Rails that are wired implicitly behind the scenes, things you're not explicitly aware of, and the first feeling people usually get is that those things just work by means of magic. It can get frustrating at first because in other programming languages and frameworks you're used to wiring everything explicitly, and you may not know how things are even working in Rails, or where they're actually connected.

The answer is convention over configuration. This is one of the main principles of Rails, and in practice it just means that all Rails projects look pretty much the same. Views go under app/views. Controllers go into app/controllers. Views names and controller actions need to be named the same. If you get comfortable with these conventions, you will understand any Rails database out there in minutes. You can onboard and get up to speed with any new project in literally minutes. It's one of the many advantages of Rails. Here's an anecdote: in the past I've hired Rails developers. Once, this one new Rails dev pushed code to production within 30 minutes of first onboarding the project (not an exageration) -- just because all Rails projects look alike. He was literally outputting production-ready code and being profitable for the company within 30 minutes of him first sitting as his desk. He hadn't seen the codebase before and was not familiar with the project. He simply just understood intuitively where everything was thanks to Rails and its principles. I still have to see something remotely similar in any other programming language / framework.

If you ever wonder how things are wired up in Rails or how Rails knows this thing is related to that other thing, the trick is usually naming. When two things are named the same (or similar, like singular/plural etc.) those things are usually related (and wired behind the scenes) like views and controllers.

It's now your turn!

You now have all the tools you need with succeed with RailsFast! There's not much more I can say to help you onboard: you should now have a live project, fully configured, and ready to go! It's now your turn to start exploring and building. Don't be afraid to break things (commit to GitHub often!), and don't be afraid to ask silly questions to the AI, just go for it!

The rest of the docs cover specific features within RailsFast.

There's a lot of functionality that comes preconfigured in RailsFast that just works so you don't need to worry much about it: auth, user uploads, backups, sending emails, payment processing integration, etc. But there's also many optional things you can easily "turn on" and leverage to build your project as if you were stacking LEGO pieces. The rest of the sections cover this.

The next section, in particular, goes over the different features that come with RailsFast. Feel free to keep reading the docs in order, or just jump straight to the section that draws your attention the most!

Good luck!

-Javi