Understand the project structure

An Astro project separates source files from files copied unchanged. Here is the shape of a small site:

astro-notes/
├── public/
│   └── robots.txt
├── src/
│   ├── components/
│   ├── layouts/
│   ├── pages/
│   └── assets/
├── astro.config.mjs
├── package.json
└── tsconfig.json

src/pages/ defines routes, and it is the one folder whose name Astro enforces: files here become URLs. src/components/ and src/layouts/ are useful conventions for reusable building blocks, not requirements, so you can reorganize them if a project demands it. Most people keep the standard names because every Astro developer recognizes them. Other source code, content, styles, and processed assets also live under src/.

Astro processes files in src/. It can bundle scripts and styles, optimize imported images, and report broken imports. This is the useful part: rename an image in src/assets/ without updating the component that imports it, and the build fails with the exact file and line. The mistake cannot reach production.

Files in public/ bypass that pipeline. Astro copies them unchanged to the output root, so public/robots.txt is served at /robots.txt. Use it for robots.txt, a web manifest, or a file that must keep an exact public path. The trade-off: a reference to a public file is only a string, so a typo there survives the build and shows up later as a 404.

Three files at the root round out the picture. astro.config.mjs holds project-wide configuration, such as integrations and build options. package.json records dependencies and the dev, build, and preview commands. tsconfig.json configures TypeScript support, which Astro projects have from the start.

A static production build normally writes to dist/. Treat that folder as disposable output: never edit it by hand, because the next build overwrites it.

Move one image between public/ and src/. Notice how its reference and build handling change, and which of the two locations catches a broken path at build time.