# Amber V2 Web Template

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

```bash
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/`.**

```text
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.**

```text
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.**

```ecr
<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](../assets/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.**

```yaml
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.**

```bash
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.**

```yaml
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.**

```bash
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.**

```bash
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.**

```bash
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.**

```bash
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](../../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](../native-preview/) before evaluating desktop or mobile output.