{"title":"Getting Started","description":"Create, test, build, and run the supported Amber V2 beta web app","section":"","version":"v2","path":"getting-started","canonical_url":"https://amberframework.org/docs/v2/getting-started","markdown_url":"https://amberframework.org/docs/v2/getting-started.md","inherited":false,"content_markdown":"# Build Your First Amber V2 Web App\n\nComplete [Installation](installation/) first. This walkthrough stays inside the\nrelease-gated web path: Grant, Micrate, and SQLite are included; no database\nserver, Node.js process, or preview generator is required.\n\n## Where the examples go\n\nStart in a parent directory where `my_app/` can be created. After `cd my_app`,\nall commands run from the application root beside `shard.yml`. File examples\nname paths relative to that root; generated output is labeled explicitly.\n\n## Create the project\n\n```bash\namber new my_app --type web\ncd my_app\n```\n\nDependencies install automatically. If you used `--no-deps`, run `shards\ninstall` now.\n\nThe generated project uses ECR, typed environment YAML, Grant, SQLite, and\nstatic routes. Its `shard.yml` pins Amber `2.0.0-beta.5` from\n`amberframework/amber` and the reviewed Grant V2 commit.\n\n## Prove the clean scaffold works\n\n```bash\namber assets check\ncrystal spec\ncrystal build src/my_app.cr -o bin/my_app\namber watch\n```\n\nOpen <http://127.0.0.1:3000>, view its source, and follow the fingerprinted\nstylesheet URL. This catches a manifest or static-route failure that a\nhomepage-only status check would miss.\n\n## Understand the generated files\n\n```text\nmy_app/\n├── .amber.yml\n├── shard.yml\n├── config/\n│   ├── application.cr\n│   ├── database.cr\n│   ├── routes.cr\n│   ├── environments/\n│   └── initializers/\n├── app/assets/\n│   ├── stylesheets/app.css\n│   ├── javascript/app.js\n│   ├── images/amber-crystal.svg\n│   ├── images/favicon.svg\n│   ├── fonts/.gitkeep\n│   └── files/.gitkeep\n├── public/assets/                    # generated; ignored by Git\n│   ├── manifest.json\n│   └── ...fingerprinted files...\n├── spec/controllers/home_controller_spec.cr\n└── src/\n    ├── my_app.cr\n    ├── controllers/\n    └── views/\n        ├── home/index.ecr\n        └── layouts/application.ecr\n```\n\nFor the complete file-by-file contract, including the intentionally empty\nextension directories, read the [V2 web template guide](../guides/web-template/).\n\n`.amber.yml` records CLI metadata. `config/environments/*.yml` uses nested V2\nsections such as `server`, `database`, `session`, and `logging`. Environment\nvariables override values, for example:\n\n```bash\nAMBER_SERVER_PORT=8080 amber watch\n```\n\n## Understand the asset boundary\n\nCLI `2.0.6` keeps authored browser files here:\n\n```text\napp/assets/\n├── stylesheets/app.css\n├── javascript/app.js\n├── images/amber-crystal.svg\n├── images/favicon.svg\n├── fonts/.keep\n└── files/.keep\n```\n\nIt generates fingerprinted files and `manifest.json` under the gitignored\n`public/assets/` directory. The commands are:\n\n```bash\namber assets build\namber assets check\n```\n\nThey must both pass before the application compiles or deploys. `amber watch`\nwill rebuild when a file under `app/assets/` changes. ECR uses logical paths\nsuch as `stylesheet_link_tag(\"stylesheets/app.css\")` and\n`image_tag(\"images/amber-crystal.svg\", alt: \"\")`; CSS uses real relative paths\nto images and fonts. The manifest supplies the fingerprinted browser URL.\n\nRead the [Asset Pipeline guide](../guides/assets/) before adding fonts,\nresponsive image variants, local JavaScript modules, or an earlier Sass or\nTypeScript build stage. It shows the exact source and output path for each.\n\n## Add a page\n\nGenerate a controller with ECR views:\n\n```bash\namber generate controller Posts index show\n```\n\nThe generator leaves request specs pending until routes exist. Add routes to\nthe generated `routes :web` block:\n\n```crystal\nget \"/posts\", PostsController, :index\nget \"/posts/:id\", PostsController, :show\n```\n\nThen enable the matching request specs and run:\n\n```bash\ncrystal tool format\ncrystal spec\n```\n\n## Add a typed request schema\n\n```bash\namber generate schema Post title:string:required body:text\n```\n\nThe Schema API is built into Amber core. See [Schema API](../guides/schema-api/)\nfor validation and controller integration.\n\n## Add a persisted resource\n\nGenerate the Grant model, request schema, controller, ECR views, request and\nmodel specs, Micrate migration, and resource route together:\n\n```bash\namber generate scaffold Pet name:string:required species:string:required adopted:bool\namber database migrate\nAMBER_ENV=test amber database migrate\ncrystal spec\n```\n\nOpen <http://127.0.0.1:3000/pets/new>. The complete file map and create/update\njourney are in [Build a Pet Tracker](../guides/pet-tracker/).\n\n## Know the beta boundary\n\nModel, scaffold, and migration generators are part of the supported web path.\nGenerated API resources and authentication remain preview, and native\ngeneration has a separate platform matrix. Read [Beta support](../beta-support/)\nbefore using those surfaces."}