Copy this page as Markdown, view its source, or open the published Markdown with an AI assistant. Copying works in local previews; external assistants need the public site URL.

Amber V2 Web Template

Run from: the parent directory where my_app/ should be created.

amber new my_app

Web is the default. amber new my_app --type web is the explicit equivalent.

The command defaults to ECR and records pg as future database intent, but the generated application has no ORM, database shard, migration requirement, Node.js dependency, or front-end bundler. Its layout resolves the local public/js/app.js ES module through a browser-native import map.

Generated project

Generated output: the complete top-level structure under my_app/.

my_app/
├── .amber.yml
├── .gitignore
├── shard.yml
├── config/
│   ├── application.cr
│   ├── routes.cr
│   ├── environments/
│   │   ├── development.yml
│   │   ├── production.yml
│   │   └── test.yml
│   └── initializers/.keep
├── db/seeds.cr
├── public/
│   ├── css/app.css
│   ├── js/app.js
│   ├── img/.keep
│   ├── favicon.ico
│   └── robots.txt
├── spec/
│   ├── spec_helper.cr
│   ├── controllers/home_controller_spec.cr
│   └── channels, jobs, mailers, models, requests, schemas/
└── src/
    ├── my_app.cr
    ├── controllers/
    │   ├── application_controller.cr
    │   └── home_controller.cr
    ├── views/
    │   ├── home/index.ecr
    │   └── layouts/application.ecr
    └── channels, jobs, mailers, models, schemas, sockets/

The empty extension directories are intentional. They give generators stable destinations without forcing unused dependencies into a new application.

First rendered page

A new Amber web application includes a small, production-shaped design system. It uses no remote fonts, images, JavaScript packages, or build step: the crystal mark, warm paper field, status chips, and responsive layout are authored in the generated ECR and public/css/app.css. Browser behavior starts in the local public/js/app.js module; the application layout maps it to the stable name app without a package manager or CDN.

Its visible content begins with:

Expected browser output: text rendered by the generated home view.

my_app                                      Amber V2 beta

Amber V2 · Web application
Your new idea starts here.

my_app is running. Your first route, view, and locally served CSS and JavaScript
are ready to shape.

Server rendered · Crystal powered · Ready to customize

First edits · Make it yours.
01 Edit the page              src/views/home/index.ecr
02 Add a route                config/routes.cr
03 Generate a controller      amber generate controller Posts

The starter carries over the site's warm neutrals, faceted geometry, editorial type hierarchy, and compact status labels. It leaves out Amber's character art and website fonts so the generated application has a coherent starting system without inheriting the framework site's identity.

File: src/views/layouts/application.ecr — the generated layout contains this complete front-end entry point.

<link rel="stylesheet" href="/css/app.css">
<script type="importmap">
  {"imports":{"app":"/js/app.js"}}
</script>
<script type="module">import "app";</script>

See Import maps for splitting the local module into application-owned controllers and utilities.

Framework pin

File: shard.yml — the generated dependency manifest uses the official repository and an exact prerelease pin.

crystal: ">= 1.20.0, < 2.0"

dependencies:
  amber:
    github: amberframework/amber
    version: 2.0.0-beta.2

Use the official repository and exact prerelease pin shown above. Moving branches and personal forks do not provide the documented beta contract.

Template freshness

The CLI embeds its web scaffold in the executable. It does not fetch a template manifest when amber new runs. That makes generation deterministic and usable offline, but a template correction requires an Amber CLI patch release.

Run from: any directory before generating a new application with Homebrew.

brew update
brew upgrade amberframework/amber_cli/amber_cli
amber --version

Updating the CLI changes future generated projects; it does not rewrite an existing application.

Typed environments

Development, test, and production settings use nested typed sections:

Files: config/environments/development.yml, config/environments/test.yml, and config/environments/production.yml — the generated files share this shape but contain environment-specific values.

name: my_app

server:
  host: 127.0.0.1
  port: 3000
  secret_key_base: "development-secret"

session:
  key: "my_app.session"
  store: "signed_cookie"
  adapter: "memory"
  expires: 0

logging:
  severity: "debug"
  colorize: true

The generated database URL is configuration metadata only. No database driver is installed and no database is contacted by the clean scaffold.

Run from: the application root. Environment overrides follow the nested key path.

AMBER_SERVER_PORT=8080 amber watch

Request pipelines

config/routes.cr defines three explicit pipelines:

web includes error handling, logging, sessions, flash, and CSRF.
static serves the files under public.
api is ready for explicit API routes and does not run by default.

The clean app registers / in the web pipeline and /* in the static pipeline. That is why both of these checks matter:

Run from: the application root while amber watch is running.

curl --fail http://127.0.0.1:3000/
curl --fail http://127.0.0.1:3000/css/app.css

Compile contract

Run from: the generated application root.

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

The clean scaffold must pass its homepage request spec, compile a native binary, serve the homepage, and serve the static stylesheet without adding a database or preview ecosystem dependency.

Extend the supported core

Run from: the application root. These generators produce core framework output.

amber generate controller Posts index show
amber generate schema Post title:string:required body:text
amber generate job Digest
amber generate mailer Welcome
amber generate channel Notifications

Controller generation does not edit routes. Add the desired routes explicitly to config/routes.cr, then enable the generated request examples.

Read Beta support before using persistence, auth, API-resource, scaffold, or native generation. Those are preview surfaces and are not part of this web-template guarantee. See the native preview boundary before evaluating desktop or mobile output.