DEV Community: hoshino tsuyoshi

Introducing A Monorepo Boilerplate for Building Rails APIs with Vite + React SPA

hoshino tsuyoshi — Sat, 02 Nov 2024 09:31:29 +0000

Introducing `rails-api-vite-easy-stack`: A Monorepo Boilerplate for Building Rails APIs with Vite + React SPA

I’m thrilled to introduce my latest passion project, rails-api-vite-easy-stack, a monorepo boilerplate designed to streamline development for those who love Rails and are excited by the simplicity and speed of Vite + React SPAs. While this project draws on my experience as a seasoned Rails engineer, it represents a personal exploration into combining these technologies rather than a production-ready setup. So, consider this an open invitation to explore, experiment, and customize as you see fit.

🏗️ Project Structure

Here's a quick look at the project layout:

Backend: A Rails application running in API mode with a GraphQL API. The setup leverages Docker and RSpec for development and testing.
Frontend: A Vite-powered React SPA using Bun as the package manager, ensuring fast builds and smooth developer experience.
GraphQL Schema Management: Organized separately to simplify backend-frontend type synchronization.

The entire monorepo structure can be summarized like this:

.
├── backend                  # Rails GraphQL API
├── frontend                 # Vite + React SPA
└── graphql-schema           # Shared GraphQL schema

🚀 Backend Highlights

The backend is a Rails API that comes with:

Authentication: Leveraging the new Rails 8 authentication generator. It’s tailored for API mode, using cookie-based sessions managed via ActionController::Cookies for simplicity and security.
Static Asset Handling: The StaticController is used to serve the SPA’s index.html, enabling seamless client-side routing.
Custom Signup Flow: Since the Rails 8 generator doesn’t handle signups out of the box, I implemented a custom flow reminiscent of devise, complete with email verification and password setup.

Here's a peek at how the backend's static asset management is handled:

# config/routes.rb
[
  "/login",
  "/me",
  "/signup"
].each { get _1, to: "static#index" }

# app/controllers/static_controller.rb
class StaticController < ApplicationController
  def index
    render plain: Rails.public_path.join('index.html').read, layout: false
  end
end

⚡ Frontend Features

The frontend is built with Vite and React, and here’s why it’s awesome:

Live Reloading: Thanks to Vite’s development server, frontend changes are reflected instantly.
GraphQL Type Safety: Using graphql-codegen, the frontend automatically generates TypeScript types from the GraphQL schema, ensuring type-safe queries and mutations.

To start the frontend, use:

# cd ./frontend
bun run dev

Proxy Setup for Development

To avoid cross-origin issues, Vite’s proxy forwards API requests to the Rails backend:

// vite.config.ts
server: {
  proxy: {
    '/graphql': 'http://localhost:3000',
  },
}

🧩 Synchronizing Backend and Frontend

Keeping backend and frontend in sync is a breeze with this workflow:

Update GraphQL Schema: Generate the schema in the backend:

   bin/rails graphql:schema:idl

Generate TypeScript Types: Use graphql-codegen in the frontend:

   bun run graphql-codegen

This integration ensures that both backend and frontend speak the same language.

🛠️ System Tests

System tests in the Rails backend use Capybara and Puma, simulating end-to-end flows. Here’s an example test for the signup process:

it 'signup -> mail verification -> set password' do
  visit '/login'
  expect(page).to have_content('Login')
  click_link 'Create an account'

  fill_in "email", with: email
  click_button "Sign up"
  expect(page).to have_content('Inviting')

  perform_enqueued_jobs(only: ActionMailer::MailDeliveryJob)
  mail_message = ActionMailer::Base.deliveries.sole
  url = URI.parse(extract_a_href_from_message(mail_message:))
  visit url.request_uri

  fill_in "password", with: SecureRandom.alphanumeric
  click_button "Set Password"
  expect(page).to have_content("hello, It's me!")
end

For more examples, check the spec/system directory in the repo.

📦 Deployment

Though the deployment process is still evolving, here are the essentials:

Build the Frontend:

   # cd ./frontend
   bun run build:move

Build the Backend Docker Image:

   # cd ./backend
   docker build -t my-spa .

The built frontend assets are synced into the Rails public directory, making it easy for Rails to serve the entire SPA.

🙏 A Word of Caution

This boilerplate is a starting point, not a silver bullet. Please customize and test thoroughly before considering it for production use. As always, feedback and contributions are welcome!

For the complete code and to dive deeper, visit rails-api-vite-easy-stack.

Thank you for taking the time to read about rails-api-vite-easy-stack! I’d love to hear your thoughts on this approach. Do you have any questions about the setup or ideas for improving it? Perhaps you've tried something similar and have insights or challenges to share. Feel free to drop your comments below—I’m looking forward to an engaging discussion and learning from your experiences!"

Happy coding! ✨

Organizing YAML files by creating directories like `config/x` in Rails

hoshino tsuyoshi — Sun, 20 Oct 2024 10:19:06 +0000

This article is a translated version of my original Japanese blog post: Railsでconfig/xみたいなディレクトリ作るとymlが分かりやすくなる説.

Hello! In this post, I’ll share a simple yet effective way to organize configuration files in a Rails application.
As your Rails project grows, keeping your config/ directory clean and manageable becomes increasingly important.
We’ll explore how creating custom directories like config/x and using config_for can make your YAML configuration files easier to manage and maintain.

Leveraging Rails.configuration and config_for for Custom Configurations

Understanding config.x.something vs config.something

The Problem: Too Many config/*.yml Files

Why the default config/ directory gets cluttered

The Solution: Organizing Custom App Settings with config/x/*.yml

Leveraging `Rails.configuration` and `config_for` for Custom Configurations

First, let’s talk about Rails.configuration and config_for.

These features were introduced in Rails 4.2 as an alternative to gems like the config gem (nostalgic) or the settings_logic gem (also nostalgic).

Here’s an excerpt from the Rails 7.0 guide:

`Rails.configuration`

To set configurations, you define them in config/application.rb or similar files:

config.x.payment_processing.schedule = :daily
config.x.payment_processing.retries  = 3
config.super_debugger = true

You can retrieve these values from anywhere in your app like this:

Rails.configuration.x.payment_processing.schedule # => :daily
Rails.configuration.x.payment_processing.retries  # => 3
Rails.configuration.x.payment_processing.not_set  # => nil
Rails.configuration.super_debugger                # => true

Now, about `config_for`

config_for is a method for loading YAML files.

It’s often used to set values in Rails.configuration.

For example, if you have a YAML file like this:

# config/payment.yml
production:
  environment: production
  merchant_id: production_merchant_id
  public_key:  production_public_key
  private_key: production_private_key

development:
  environment: sandbox
  merchant_id: development_merchant_id
  public_key:  development_public_key
  private_key: development_private_key

You can set these values in config/application.rb as follows:

# config/application.rb
module MyApp
  class Application < Rails::Application
    config.payment = config_for(:payment)
  end
end

In this case, you’d retrieve the values like this:

Rails.configuration.payment['merchant_id'] # => production_merchant_id or development_merchant_id

You can also set the value using config.x.payment = config_for(:payment) if you prefer, like this:

# config/application.rb
module MyApp
  class Application < Rails::Application
    config.x.payment = config_for(:payment)
  end
end

Then, you can retrieve the values like this:

Rails.configuration.x.payment['merchant_id'] # => production_merchant_id or development_merchant_id

What’s the difference between `config.x.something` and `config.something`?

From an implementation standpoint, the key difference is that config.x.something allows for nesting.

# Example
config.x.payment_processing.schedule = :daily

Other than that, the Rails guide doesn’t suggest any major differences. However, I personally feel like adding x gives it a custom, localized feel, kind of like custom HTTP headers.

The Problem: Too Many `config/*.yml` Files

Whether you use x or not, as you make use of these methods, you’ll end up with lots of YAML files in the config/ directory.

Here’s an example of what the config/ folder might look like:

application.rb
bar.yml
baz.yml
boot.rb
cable.yml
corge.yml
database.yml
environment.rb
environments/
foo.yml
fred.yml
garply.yml
grault.yml
initializers/
locales/
newrelic.yml
plugh.yml
puma.rb
quux.yml
qux.yml
routes.rb
sidekiq.yml
spring.rb
storage.yml
thud.yml
waldo.yml
webpack/
webpacker.yml

The mess

It’s not the sheer number of files that’s the problem. The issue is that it becomes difficult to distinguish between YAML files provided by Rails or third-party gems and your custom configurations.

For instance:

config/cable.yml and config/database.yml come from Rails.
config/sidekiq.yml comes from the sidekiq gem.
config/newrelic.yml comes from the New Relic gem.
All other config/*.yml files are custom app configurations set using config_for.

In summary, if we were to comment on the files in config/, it might look like this:

config/
├── application.rb
├── database.yml   # from Rails
├── cable.yml      # from Rails
├── sidekiq.yml    # from Sidekiq gem
├── newrelic.yml   # from New Relic gem
├── bar.yml        # custom app config
└── foo.yml        # custom app config

Now compare that to a cleaner structure with config/x/:

config/
├── application.rb
├── x/           # custom app configs live here
│   ├── bar.yml
│   └── foo.yml
├── database.yml
└── cable.yml

Even experienced developers can have a hard time distinguishing between these files at a glance.

The Solution: Organizing Custom App Settings with `config/x/*.yml`

Here’s my suggestion: config_for can actually load files from directories other than config/. This changed in Rails 5.0 (see the relevant commit here).

So, we could rewrite config/application.rb like this:

# config/application.rb
module MyApp
  class Application < Rails::Application
    config.x.bar   = config_for(Rails.root.join('config/x/bar.yml'))
    config.x.baz   = config_for(Rails.root.join('config/x/baz.yml'))
    config.x.corge = config_for(Rails.root.join('config/x/corge.yml'))
    # ...snip...
    config.x.waldo = config_for(Rails.root.join('config/x/waldo.yml'))
  end
end

By doing this, we can easily distinguish between YAML files provided by Rails or third-party gems and our custom configurations.

Here’s how the config/ folder would look:

# config/
application.rb
boot.rb
cable.yml        # From Rails
database.yml     # From Rails
environment.rb
environments/
initializers/
locales/
newrelic.yml     # From New Relic gem
puma.rb
routes.rb
sidekiq.yml      # From Sidekiq gem
spring.rb
storage.yml      # From Rails
webpack/
webpacker.yml    # From Rails
x/

And in config/x/:

# config/x/
bar.yml          # Custom for this Rails app
baz.yml          # Custom for this Rails app
corge.yml        # Custom for this Rails app
foo.yml          # Custom for this Rails app
fred.yml         # Custom for this Rails app
garply.yml       # Custom for this Rails app
grault.yml       # Custom for this Rails app
plugh.yml        # Custom for this Rails app
quux.yml         # Custom for this Rails app
qux.yml          # Custom for this Rails app
thud.yml         # Custom for this Rails app
waldo.yml        # Custom for this Rails app

By separating the files like this, everything becomes much clearer!

Conclusion

In this post, we discussed how creating a config/x directory can help you organize custom YAML configuration files more efficiently in Rails. By separating app-specific settings from third-party and framework-provided configurations, you not only make your codebase easier to manage, but also improve the clarity for developers who need to understand the system at a glance.

This structure encourages a cleaner, more modular approach, which is particularly beneficial for scaling and maintaining large Rails applications.