Skip to content

getting-started.md

Latest commit

 

History

History
203 lines (147 loc) · 4.47 KB

getting-started.md

File metadata and controls

203 lines (147 loc) · 4.47 KB
Raw

Getting Started

This guide walks through creating a minimal Amber V2 application from scratch. By the end, you will have a working web server that responds to HTTP requests with a rendered HTML page.

Prerequisites

Create a New Project

Create a new Crystal project using crystal init:

crystal init app my_app
cd my_app

Add Amber as a Dependency

Edit shard.yml to add the Amber framework:

name: my_app
version: 0.1.0

dependencies:
  amber:
    github: amberframework/amber
    branch: v2-dev

crystal: ">= 1.0.0"

Install dependencies:

shards install

Project Structure

Create the following directory structure:

my_app/
  src/
    my_app.cr
    controllers/
      home_controller.cr
    views/
      home/
        index.ecr
      layouts/
        application.ecr

Create the directories:

mkdir -p src/controllers src/views/home src/views/layouts

Create a Controller

Create src/controllers/home_controller.cr:

require "amber/controller/base"

class HomeController < Amber::Controller::Base
  def index
    @title = "Welcome"
    render("index.ecr")
  end
end

The render macro looks for the template at src/views/home/index.ecr based on the controller name. It wraps the template in the default layout at src/views/layouts/application.ecr.

Create Views

Create the layout at src/views/layouts/application.ecr:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>My App</title>
</head>
<body>
  <%= content %>
</body>
</html>

The <%= content %> placeholder is where the action template is inserted.

Create the index template at src/views/home/index.ecr:

<h1><%= @title %></h1>
<p>Hello from Amber V2!</p>

Configure the Server

Edit src/my_app.cr to configure routing and start the server:

require "amber"
require "./controllers/*"

Amber::Server.configure do
  pipeline :web do
    plug Amber::Pipe::Error.new
    plug Amber::Pipe::Logger.new
  end

  routes :web do
    get "/", HomeController, :index
  end
end

Amber::Server.start

This configures a :web pipeline with error handling and request logging, maps GET / to HomeController#index, and starts the HTTP server.

Run the Application

crystal run src/my_app.cr

Visit http://localhost:3000 in your browser to see your page.

Configuration

By default, Amber listens on localhost:3000. To change the host or port, create a YAML configuration file or use environment variables.

Environment Variables

AMBER_SERVER_HOST=0.0.0.0 AMBER_SERVER_PORT=8080 crystal run src/my_app.cr

YAML Configuration

Create config/environments/development.yml:

name: "my_app"

server:
  host: "localhost"
  port: 3000
  secret_key_base: "a_random_string_at_least_32_characters_long"

logging:
  severity: "debug"
  colorize: true

See the Configuration Guide for all available settings.

Adding More Routes

Add additional routes and controllers as your application grows:

Amber::Server.configure do
  pipeline :web do
    plug Amber::Pipe::Error.new
    plug Amber::Pipe::Logger.new
    plug Amber::Pipe::Session.new
    plug Amber::Pipe::Flash.new
    plug Amber::Pipe::CSRF.new
  end

  routes :web do
    get "/", HomeController, :index
    resources "users", UsersController
    resources "posts", PostsController
  end
end

The resources macro generates all seven RESTful routes (index, new, create, show, edit, update, destroy) for a given controller.

Next Steps

  • Routing -- Route definitions, resources, namespaces, constraints, and API versioning
  • Configuration -- Environment YAML, environment variables, and custom config sections
  • Action Helpers -- Form helpers, URL helpers, asset tags, and text formatting
  • Schema API -- Type-safe, validated parameter handling
  • WebSockets -- Real-time communication with channels and presence tracking
  • Background Jobs -- Asynchronous job processing
  • Mailer -- Email delivery with SMTP and memory adapters
  • Testing -- Request helpers, assertions, and controller testing
  • Markdown -- Markdown rendering with GFM support
  • Migration Guide -- Migrating from Amber V1 to V2