What is Full-Stack development? A QuickStart Tutorial

Backend (Rails 7.1) Setup

We’ll create a minimal Task model with title, completed flag, and timestamps. Use Rails API mode so controllers render JSON by default.

# Generate model and controller
rails g model Task title:string completed:boolean
rails db:create db:migrate
rails g controller api/v1/tasks --api

Migration (db/migrate/xxxx_create_tasks.rb):

class CreateTasks < ActiveRecord::Migration[7.1]
  def change
    create_table :tasks do |t|
      t.string :title, null: false
      t.boolean :completed, default: false, null: false

      t.timestamps
    end
  end
end

Model (app/models/task.rb):

class Task < ApplicationRecord
  validates :title, presence: true, length: { maximum: 255 }
end

Configure CORS so the React app (served from a different port in development) can call the API. Add to Gemfile:

gem 'rack-cors', '~> 1.1'

Then config (config/initializers/cors.rb):

Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins 'http://localhost:3000' # React dev server
    resource '/api/*', headers: :any, methods: %i[get post put patch delete options]
  end
end

API Endpoints and Controllers

Implement a simple JSON API under /api/v1/tasks. Note: follow strong params and return appropriate HTTP status codes.

# config/routes.rb
Rails.application.routes.draw do
  namespace :api do
    namespace :v1 do
      resources :tasks
    end
  end
end

# app/controllers/api/v1/tasks_controller.rb
module Api
  module V1
    class TasksController < ApplicationController
      before_action :set_task, only: %i[show update destroy]

      def index
        @tasks = Task.order(created_at: :desc)
        render json: @tasks
      end

      def show
        render json: @task
      end

      def create
        @task = Task.new(task_params)
        if @task.save
          render json: @task, status: :created
        else
          render json: { errors: @task.errors.full_messages }, status: :unprocessable_entity
        end
      end

      def update
        if @task.update(task_params)
          render json: @task
        else
          render json: { errors: @task.errors.full_messages }, status: :unprocessable_entity
        end
      end

      def destroy
        @task.destroy
        head :no_content
      end

      private

      def set_task
        @task = Task.find(params[:id])
      rescue ActiveRecord::RecordNotFound
        render json: { error: 'Task not found' }, status: :not_found
      end

      def task_params
        params.require(:task).permit(:title, :completed)
      end
    end
  end
end

Troubleshooting tip: If you get 500 errors on JSON rendering, inspect server logs and run the controller action in rails console to validate model behavior. Use rails db:rollback and re-run migrations to fix schema drift.

Frontend (React 18) Setup

Create a React 18 app (using your preferred tooling—Vite is recommended for speed, or create-react-app). Below is a minimal example using fetch and functional components.

# Using Vite (example)
npm create vite@latest task-manager-client --template react
cd task-manager-client
npm install
npm run dev

Minimal tasks client (src/App.jsx):

import React, { useEffect, useState } from 'react';

function App() {
  const [tasks, setTasks] = useState([]);
  const [title, setTitle] = useState('');

  async function fetchTasks() {
    const res = await fetch('http://localhost:3001/api/v1/tasks');
    if (!res.ok) throw new Error('Failed to fetch tasks');
    setTasks(await res.json());
  }

  useEffect(() => { fetchTasks().catch(console.error); }, []);

  async function createTask(e) {
    e.preventDefault();
    const res = await fetch('http://localhost:3001/api/v1/tasks', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ task: { title } })
    });
    if (res.ok) {
      setTitle('');
      fetchTasks();
    } else {
      console.error('Create failed');
    }
  }

  async function toggleComplete(id, completed) {
    await fetch(`http://localhost:3001/api/v1/tasks/${id}`, {
      method: 'PATCH',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ task: { completed: !completed } })
    });
    fetchTasks();
  }

  return (
    <div>
      <h1>Tasks</h1>
      <form onSubmit={createTask}>
        <input value={title} onChange={e => setTitle(e.target.value)} placeholder="New task" />
        <button type="submit">Add</button>
      </form>
      <ul>
        {tasks.map(t => (
          <li key={t.id}>
            <label>
              <input type="checkbox" checked={t.completed} onChange={() => toggleComplete(t.id, t.completed)} />
              {t.title}
            </label>
          </li>
        ))}
      </ul>
    </div>
  );
}

export default App;

Frontend Code Breakdown

For beginners, here's a concise walkthrough of the key parts of the src/App.jsx example so you can reason about behavior and extend it safely.

• State hooks: useState stores tasks and the title input. Keep state minimal and derive views from it.
• Data fetching: fetchTasks calls /api/v1/tasks. We call it on mount via useEffect. Handle non-OK responses and surface errors to the user or to a logger.
• Create flow: createTask posts JSON with { task: { title } }. Use appropriate headers (Content-Type: application/json) and check response codes (201 Created vs 422 Unprocessable Entity).
• Update flow: toggleComplete patches the single task. For production, prefer optimistic UI with rollback on error; React Query simplifies this pattern.
• Error handling: Always catch network errors. For example, wrap fetch calls in try/catch and show a user-friendly message. Avoid leaving the UI in an inconsistent state when requests fail.
• Security: Never store secrets in client code. In production, prefer SameSite cookies with CSRF protection or JWT with short expiry & refresh tokens. Ensure CORS and server-side validation are in place.
• Performance and UX: Debounce rapid interactions (typing/save), show loading/saving indicators (see the TaskItem example above), and paginate or lazy-load large lists.

These principles help you evolve the quickstart into a robust frontend: separate presentational components (TaskItem) from data-loading logic, and consider using libraries like React Query (v4+) for caching and background revalidation when your app grows.

Connect Frontend and Backend

Run Rails API on port 3001 (example) and React dev server on 3000. Ensure CORS is configured as shown earlier. Use JSON endpoints under /api/v1/*. For session-based auth you can enable cookies and CSRF protection; for APIs JWT or OAuth are common choices.

Troubleshooting: If your browser blocks requests, check the console for CORS errors. Confirm the Access-Control-Allow-Origin header is present on API responses and matches the React origin. Use curl to test endpoints independent of the browser:

curl -i http://localhost:3001/api/v1/tasks

Run & Deploy with Docker

Use docker-compose to bring up Rails, Postgres, and optionally the React build. Example docker-compose.yml (simplified):

version: '3.8'
services:
  db:
    image: postgres:14
    environment:
      POSTGRES_PASSWORD: password
    volumes:
      - db-data:/var/lib/postgresql/data
  web:
    build: .
    command: bundle exec rails server -b 0.0.0.0 -p 3001
    ports:
      - '3001:3001'
    environment:
      DATABASE_URL: postgres://postgres:password@db:5432/postgres
    depends_on:
      - db
volumes:
  db-data:

Dockerfile (Rails):

FROM ruby:3.2
WORKDIR /app
COPY Gemfile* ./
RUN bundle install
COPY . .
CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "3001"]

For production deployments, build the React app (npm run build) and serve static assets from a CDN or via an assets server; proxy API calls to the Rails service.

Best Practices

• Validate input in controllers and models (Rails strong params + model validations).
• Use environment variables for secrets; do not commit .env files. In Rails use credentials or environment vars in CI.
• Prefer explicit JSON schemas for public APIs (OpenAPI/Swagger) to avoid contract drift.
• Use database transactions and background jobs (Sidekiq) for long-running tasks.
• Measure performance (log response times, use monitoring tools) and add indexes on frequently queried columns.

Common Challenges

The items below are frequent pain points and practical mitigations.

• CORS errors: Ensure server sets Access-Control-Allow-Origin for expected origins. Use rack-cors in Rails when serving an API to a separate frontend origin.
• State management complexity: Server state and client state often diverge. Use React Query or Redux Toolkit to centralize async state and caching, and prefer optimistic updates with rollback on failure.
• Database migrations and schema drift: Apply migrations in CI, and use a staging environment that mirrors production. Test migrations on a copy of production data if possible before running them live.
• Security vulnerabilities: Prevent SQL injection via parameterized queries (ActiveRecord does this by default). Validate and sanitize inputs, enforce strong authentication, rotate secrets, and enable HTTPS in production.
• Authentication/Authorization: Decide between session cookies (stateful) and JWT (stateless). For APIs consumed by SPAs, JWT with refresh tokens or cookie-based SameSite=strict sessions are common. Always verify tokens server-side and enforce scopes/roles.
• API versioning: Use /api/v1/ prefix and plan migrations for breaking changes (deprecate old endpoints progressively).
• Performance under load: Add indexes, cache responses (Redis), and profile slow queries with EXPLAIN ANALYZE for PostgreSQL.

Troubleshooting tips:

• When fetch requests return non-JSON, check that Rails controllers render JSON and that middleware hasn't modified responses.
• If migrations fail in CI, check DB permissions and run migrations locally against a test database to reproduce errors.
• Use logs and breakpoints (pry for Rails, browser devtools for React) to trace request/response flows.