Astro Final Project — Build a Complete Production Site

In this tutorial, you will learn about Astro Final Project. We cover key concepts, practical examples, and best practices to help you master this topic.

Build a complete production-ready Astro site with content collections, dynamic routes, SSR, API endpoints, view transitions, and deployment to a hosting platform.

In this project, you'll combine everything you've learned about Astro to build a documentation portal with blog, search, authentication, and deployment.

What You'll Build

A documentation portal with: markdown-based docs, a blog with content collections, user authentication via middleware, search API endpoint, view transitions, and deployment.

Why It Matters

This project simulates a real-world Astro application. Completing it proves you can build and ship a full Astro site independently.

Real-World Use

This project mirrors DodaTech's own tutorial platform architecture, demonstrating how Astro scales to production content sites.

flowchart TD
    A[Project Root] --> B[Content Collections]
    A --> C[SSR Pages]
    A --> D[API Endpoints]
    A --> E[Middlware]
    A --> F[Deployment]
    B --> G[Static Docs]
    C --> H[Dynamic Dashboard]
    D --> I[Search + Forms]
    style A fill:#ff5a03,color:#fff

Step 1: Project Setup

npm create astro@latest docs-portal -- --template basics
cd docs-portal
npm install
npm run dev

Step 2: Content Collections

Create src/content/config.ts:

import { defineCollection, z } from "astro:content";

const docsCollection = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string().max(165),
    category: z.enum(["getting-started", "guides", "advanced"]),
    order: z.number(),
  }),
});

const blogCollection = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.date(),
    author: z.string(),
    tags: z.array(z.string()).default([]),
  }),
});

export const collections = { docs: docsCollection, blog: blogCollection };

Step 3: Dynamic Routes

Create src/pages/docs/[...slug].astro to render docs from the collection and src/pages/blog/[slug].astro for blog posts.

Step 4: Layout and Components

Build a BaseLayout with navigation, a DocLayout with sidebar, and a BlogLayout with post metadata header. Create components for cards, breadcrumbs, and a search bar.

Step 5: SSR with Middleware

Enable hybrid mode with a Node.js adapter. Add authentication middleware that checks for a session cookie on /dashboard/* routes.

Step 6: API Endpoints

Create src/pages/api/search.ts that accepts query params and returns matching docs:

import { getCollection } from "astro:content";

export async function GET({ request }) {
  const url = new URL(request.url);
  const query = url.searchParams.get("q")?.toLowerCase();
  const docs = await getCollection("docs");
  const results = docs.filter(doc =>
    doc.data.title.toLowerCase().includes(query) ||
    doc.data.description.toLowerCase().includes(query)
  );
  return new Response(JSON.stringify(results), {
    headers: { "Content-Type": "application/json" },
  });
}

Step 7: View Transitions

Add <ViewTransitions /> to the base layout. Apply transition:name to the page title element and use data-astro-transition="slide" on navigation links.

Step 8: Deployment

Build and deploy:

npm run build
# Deploy dist/ to Netlify, Vercel, or your preferred host

Common Mistakes

1. Not planning the content model first: Define your schemas before writing content. Changing schemas later requires updating all frontmatter.
2. Overcomplicating the middleware: Start with simple auth middleware. Add complexity (roles, permissions) only when needed.
3. Skipping error boundaries: Every SSR page needs error handling. A bug in one page shouldn't crash the entire site.
4. Not optimizing images: Use the <Image /> component for all user-facing images. Raw <img> tags miss optimization.
5. Forgetting SEO metadata: Every page should have a title and description meta tag. Use a layout component to enforce this.

Practice Questions

1. What rendering strategy would you use for a documentation portal? Answer: Hybrid mode: static for docs (pre-rendered), SSR for user dashboards (personalized), and API endpoints for search.

2. How do you structure content collections for scalability? Answer: Create separate collections for each content type (docs, blog, tutorials) with specific schemas and validation.

3. Why add view transitions to a documentation site? Answer: They make navigation between docs feel instant, improving the reading experience and perceived performance.

4. What is the benefit of middleware for this project? Answer: Centralized authentication, request logging, and security headers without per-page code duplication.

Challenge

Extend the project with: user profiles stored in Astro DB, comment system for blog posts with form validation, rate limiting on the search API, and automated CI/CD deployment to Cloudflare Pages.

Mini Project

Deploy your completed documentation portal to a hosting platform. Set up a custom domain, enable HTTPS, configure redirects for old URLs, and verify the sitemap and RSS feed are accessible.

FAQ

What's Next

Congratulations on completing the Astro guide! Explore React Guide to deepen your understanding of the most popular UI library used with Astro islands.