Project structure · Frontend
Astro project structure
Opens with creditsFor developers building content-heavy websites (blogs, docs, society or portfolio sites) that should load fast with little JavaScript. The example is a university tech society site from the blog template: content collections for posts, events and the team, a couple of React islands, an Action-backed join form, and a few on-demand pages through the Node adapter while everything else stays static.
Curated by Tauseef FayyazBeginner164 files and foldersAstro 7.3, Node 22.12+, TypeScript 6Checked October 2026How it grows
Each stage opens the explorer there
- 1Day 1What the scaffold and your first hour give you47 files and folders
- 2GrowingWhat a real app with features and tests adds+62 files and folders
- ProductionWhat running it for real users adds+29 files and foldersOpens with credits
- ExpertWhat a team needs to keep it healthy for years+26 files and foldersOpens with credits
How it is organised
- Static by default. Pages are prerendered at build time; only pages that need the request (account, join results, health) export `prerender = false`.
- Ship HTML, not JavaScript. Use .astro components for everything, and make a React island only for the parts that are truly interactive, with the laziest `client:*` directive that works.
- Content is data. Every Markdown or data file belongs to a collection in src/content.config.ts with a Zod schema, so a bad frontmatter field fails the build instead of the page.
- Server code stays on the server. Forms call Actions, database and email code lives in src/lib, and islands never import it.
- Environment variables are declared once in `env.schema` and read through `astro:env`, so a missing secret fails at startup and nothing secret is marked `client`.
- Images you show go in src/assets and through `<Image />`; public/ is only for files that need a fixed URL.
- Use one UI framework for islands. Astro can mix React, Vue and Svelte, but a team rarely benefits from paying for two.
At the top of the project
Open one in the explorer for the full story
- my-site/
- .husky/Git hooks managed by husky, created by `npx husky init`.2 inside
- .vscode/Shared VS Code settings from the template.3 inside
- .astro/Types and the content data store that Astro generates.
- dist/Build output from `astro build`.
- node_modules/Installed packages.
- coverage/Coverage reports from `vitest run --coverage`.
- docs/Project documentation that is too long for the README.1 inside
- public/Files copied to the build output exactly as they are.4 inside
- scripts/Small Node scripts for content and maintenance work.1 inside
- src/All source code and content that Astro processes.12 inside
- tests/Unit, component and browser tests.3 inside
- .envLocal secrets and settings: DATABASE_URL, email API key.
- .env.exampleEvery variable the site needs, with safe sample values.
- .gitignoreIgnores dist, .astro, node_modules, logs and .env files.
- .nvmrcThe Node version for this project, for example 24.
- .prettierrc.mjsPrettier config with prettier-plugin-astro.
- AGENTS.mdInstructions for AI coding agents, written by create-astro.
- CLAUDE.mdA symlink to AGENTS.md so Claude Code reads the same instructions.
- README.mdHow to run, build and contribute to the site.
- astro.config.mjsAstro configuration: site URL, integrations, adapter, fonts, env schema, CSP.
- commitlint.config.jsEnforces Conventional Commit messages.
- drizzle/SQL migrations generated by drizzle-kit.2 inside
- drizzle.config.tsdrizzle-kit settings: schema path, migrations folder, database URL.
- eslint.config.jsESLint flat config with eslint-plugin-astro and TypeScript rules.
- package-lock.jsonExact versions of every installed package.
- package.jsonDependencies, the Node engine range and the scripts: dev, build, preview, astro.
- tsconfig.jsonTypeScript settings: extends astro/tsconfigs/strict and includes the generated .astro types.
- vitest.config.tsVitest config built with `getViteConfig()` from astro/config.
Learn more on Sefism
Roadmaps, cheat sheets and projects that go with Astro.
- RoadmapFrontend development roadmapHTML, CSS, JavaScript and a framework
- RoadmapWordPress and Shopify roadmapBusiness sites and online stores
- Roadmap· PlaywrightQA and test automation roadmapManual testing to automated suites
- Cheat sheetFrontend development cheat sheetHTML, CSS, JavaScript and a framework.
- Cheat sheetWordPress and Shopify cheat sheetBusiness sites and online stores.
- FYP idea· BeginnerGovernment Website Accessibility and Performance Observatory with Monthly Public ReportsBuild an open observatory that checks a country's public sector websites every month for accessibility errors, mobile performance, HTTPS and security headers, and whether key pages are available in the local language, then publishes the results as open data and a simple league table. People depend on these sites for exams, licences, taxes and benefits, yet nobody tracks their quality over time. A good first project in crawling, automated testing and honest data presentation.
- FYP idea· IntermediateLecture PDF Accessibility Checker and Accessible HTML Converter for UniversitiesBuild a tool that checks the PDF handouts and slides teachers share on a university learning portal, explains accessibility failures in plain language, and converts the worst ones into accessible HTML with real headings, reading order, alt text prompts and readable tables. Most lecture PDFs are exported from slides with no structure, which locks out blind and low-vision students. The project combines document parsing, a teacher-friendly report and a study with students who use screen readers.
- FYP idea· AdvancedAI Agent Readiness Audit for Websites: Can a Browser Agent Complete Your Key Tasks?Build an audit tool that sends real browser agents to complete a site's key tasks, such as finding a product, booking a slot or filling a form, then explains every failure in terms of the page: unlabelled buttons, hidden state, broken focus order or missing structured data. More customers will reach small businesses through AI agents, and most sites have never been tested that way. The output is a repeatable score and a fix list a web developer can act on.
- QuestionWhat should I learn to become a web developer, and in what order?Learn the web platform first (HTML, CSS, JavaScript, how HTTP works), then one frontend framework, then a backend with a database, and build a real project at each stage. If you already know WordPress, you are not starting over: your HTML, CSS and PHP experience transfers.
See 9 moreShow fewer
- QuestionHow do I build a developer portfolio as a beginner with nothing to show?Start with two or three small but complete projects that solve a real problem, each with a clear README, screenshots and a live link or easy run steps. Put them on a simple one-page site or a tidy GitHub profile. Depth and finish matter far more than the number of projects or a fancy design.
- QuestionI understand tutorials but cannot build anything myself. Why does coding feel so different when I am alone?Tutorials train recognition, not production. When you follow along, someone else makes every decision. Building alone requires you to break a problem down and make choices, which is a separate skill. Build it with small projects, planning on paper first, and a rule to struggle before you look anything up.
- QuestionWhat projects should I build in my first year of university?Build small, finished projects that solve problems you or people around you actually have: a script that automates a chore, a command line tool, a simple website for a society or family business. First year is about finishing things and using Git, not about impressive ideas.
- Resource· GuideMDN Web DocsMDN Web Docs is Mozilla's open, community-maintained reference for HTML, CSS, JavaScript, HTTP and browser APIs, with browser compatibility tables on every page and a structured Learn area for beginners. It is free, and a paid MDN Plus tier adds extras such as AI help and collections. It suits every web developer, from someone writing their first page to a senior engineer checking exactly how an API behaves across browsers.
- Resource· GuideMarkdown GuideA free, open-source reference that explains every piece of Markdown syntax with side-by-side examples, and shows which apps support which extensions. The fastest way to settle how a table, a nested list or a footnote should be written.
- Resource· CourseLearn AccessibilityA free web.dev course on digital accessibility, from what it is and how it is measured to ARIA, focus, colour and contrast, forms, design systems and testing with assistive technology. Useful for designers and developers alike.
- Resource· GuideThe TypeScript HandbookThe TypeScript Handbook is the official, free guide to TypeScript's type system from the TypeScript team, written for working programmers and kept current with each release. It covers everyday types, narrowing, functions, object types, generics, type manipulation, classes and modules, and it is designed to be read in a few hours. It suits JavaScript developers adopting TypeScript and anyone who writes types by copying patterns without understanding them.
- Resource· GuidePlaywright DocumentationThe official documentation for Playwright, Microsoft's open-source framework for end-to-end testing in real Chromium, Firefox and WebKit browsers, with mobile emulation. It walks you from installation to your first test, then covers locators, assertions, fixtures, authentication, API testing, parallel runs and CI. Tools such as the code generator, UI mode and trace viewer make first tests easy. It suits developers and QA engineers adding reliable browser tests to a web app.
- Resource· GuideGitHub Actions DocumentationThe official documentation for GitHub Actions, GitHub's built in CI/CD and automation system: workflow syntax, triggers, runners, caching, artifacts, environments, secrets and OpenID Connect deployments to AWS, Azure and Google Cloud. Actions is free for public repositories on standard runners, so it is the CI tool most students and open source projects learn first. It suits developers setting up tests and deployments for the first time.
Checked against 20 official sources, October 2026. If something has changed, the docs win.Show sourcesHide sources
- Astro: Install and set up
- Astro: Project structure
- Astro: Content collections
- Astro: Islands architecture
- Astro: Server islands
- Astro: Actions
- Astro: Middleware
- Astro: On-demand rendering
- Astro: Sessions
- Astro: Type-safe environment variables
- Astro: Routing (including advanced routing)
- Astro: Internationalization routing
- Astro: Testing
- Astro: Upgrade to v6
- Astro: Upgrade to v7
- Astro examples: basics and blog templates
- @astrojs/node adapter
- Sentry: Astro SDK
- Drizzle ORM documentation
- Pagefind documentation
Best practices and checklists for this stack
Picked from the other libraries by shared topics.
Best practices
See all- React Best PracticesModern React best practices for 2026: pure components, lean state, fewer effects, React Compiler, form actions, accessibility and testing.
- Modern CSS Best PracticesModern CSS best practices: cascade layers, low specificity, custom properties, Grid and Flexbox layout, responsive design, container queries, :has() and nesting, plus Tailwind CSS v4 tips.
- TypeScript Best PracticesModern TypeScript best practices for 2026: strict settings, TypeScript 7, modeling data with unions, safe narrowing, runtime validation, generics and typed linting.
Checklists
See all- Web Accessibility ChecklistA practical web accessibility checklist built on WCAG 2.2 level AA, with a severity and a concrete way to verify every check.
- Web Performance ChecklistA practical web performance checklist built on Core Web Vitals: LCP, INP and CLS, with a severity and a concrete way to verify every check.
Work with me
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com