Copy as Markdown View as Markdown
Open in Claude
1.4.1
2.0

Build Your First Amber V2 Web App

Complete Installation first. This walkthrough stays inside the release-gated core: no ORM, database, Node.js, or preview generator is required.

Create the project

amber new my_app --type web
cd my_app

Dependencies install automatically. If you used --no-deps, run shards install now.

The generated project uses ECR, typed environment YAML, and static routes. Its shard.yml pins Amber 2.0.0-beta.2 from amberframework/amber.

Prove the clean scaffold works

crystal spec
crystal build src/my_app.cr -o bin/my_app
amber watch

Open http://127.0.0.1:3000. Also load http://127.0.0.1:3000/css/app.css; this catches a missing static route that a homepage-only check would miss.

Understand the generated files

my_app/
├── .amber.yml
├── shard.yml
├── config/
│   ├── application.cr
│   ├── routes.cr
│   └── environments/
├── public/css/app.css
├── public/js/app.js
├── spec/controllers/home_controller_spec.cr
└── src/
    ├── my_app.cr
    ├── controllers/
    └── views/
        ├── home/index.ecr
        └── layouts/application.ecr

.amber.yml records CLI metadata. config/environments/*.yml uses nested V2 sections such as server, database, session, and logging. Environment variables override values, for example:

AMBER_SERVER_PORT=8080 amber watch

Add a page

Generate a controller with ECR views:

amber generate controller Posts index show

The generator leaves request specs pending until routes exist. Add routes to the generated routes :web block:

get "/posts", PostsController, :index
get "/posts/:id", PostsController, :show

Then enable the matching request specs and run:

crystal tool format
crystal spec

Add a typed request schema

amber generate schema Post title:string:required body:text

The Schema API is built into Amber core. See Schema API for validation and controller integration.

Know the beta boundary

Model, scaffold, API-resource, and auth generators currently emit persistence-backed output. Native generation has a separate platform matrix. They are preview surfaces, not part of this clean web-app guarantee. Read Beta support before using them.