Learning Astro - Starting an Astro Project

#Introduction

The theory in episodes 1 and 2 is enough — now it is time to get your hands on the keyboard. This episode 3 is all practice: you will create an Astro project from scratch, explore its structure and key files, run the dev server, and then set up TypeScript, ESLint, and formatting so the project is tidy from day one.

Many beginners jump straight into code and ignore the tooling foundation. Yet correct configuration will save time throughout the whole series: TypeScript catches errors before the build, ESLint maintains quality, and Prettier keeps code formatting consistent among team members.

Get your terminal ready and follow along step by step — by the end of the episode, you will have a clean Astro project ready to develop.

#Creating a Project with create-astro

#Running the Scaffolding Command

Make sure you are in the directory where the project will be created, then run:

npm create astro@latest

npm create astro@latest is the official entry point. This command asks a few things: the project name, the template (Empty, Basics, Blog, or Docs), whether to use TypeScript, and dependency installation. For practice, choose the Basics template with TypeScript Strict, then confirm the dependency installation.

#The Direct Project Name Alternative

You can also specify the project name directly in the same command, making the wizard shorter:

npm create astro@latest situs-konten -- --template basics --typescript strict

The --typescript strict flag enables TypeScript in its strictest mode — the recommended choice for serious codebases.

#Project Structure and Key Files

#The Scaffolded Directory Map

After the process finishes, your project structure will look like this:

situs-konten/
├── public/             # static assets without processing
├── src/
│   ├── components/     # reusable components
│   ├── layouts/        # page layouts
│   └── pages/          # page routes
├── astro.config.mjs    # Astro configuration
├── tsconfig.json       # TypeScript configuration
└── package.json        # scripts and dependencies

The src/pages folder is the center of routing: files placed there become pages directly. The public folder is copied as-is into dist/ at build time — perfect for favicons, logos, and unprocessed files.

#The Main Configuration Files

astro.config.mjs is the center of Astro configuration. Its initial content is simple:

Default astro.config.mjs

import { defineConfig } from "astro/config";
 
export default defineConfig({
  site: "https://contoh.dev",
});

The site property in defineConfig({ site: "..." }) is required for features like sitemap and canonical URLs — you will fill it with your production domain later in episode 8.

#Running the Dev Server and Live Reload

#The Dev Command

From inside the project folder, run the dev server:

npm run dev

The terminal output will show the URL http://localhost:4321. Open that URL in the browser — your first Astro page is now alive. Try editing the file src/pages/index.astro, and notice that the change is visible immediately without a manual refresh. This is live reload and HMR powered by Vite.

#Running Build and Preview

To see the production result:

npm run build
npm run preview

npm run build produces the dist/ folder ready to deploy. npm run preview serves that build output locally so you can inspect it before uploading to hosting.

#TypeScript, ESLint, and Formatting Configuration

#TypeScript Strict

Astro uses a tsconfig.json that extends astro/tsconfigs/strict. This strict mode enables null checks, unused variable checks, and many other rules. Verify its contents:

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}

To type-check the whole project, run npx astro check. This command reports type errors in .astro and .ts files — make it a habit to run it before pushing.

#ESLint for Code Quality

Astro does not install ESLint by default. You can add the official community configuration:

npm install -D eslint eslint-plugin-astro
npx eslint --init

Once installed, npx eslint src scans the whole src folder and reports potential issues like unused variables.

#Prettier for Formatting

Consistent formatting can be automated with Prettier and the Astro-specific plugin:

npm install -D prettier prettier-plugin-astro

Then create a .prettierrc file containing { "plugins": ["prettier-plugin-astro"] }, and run npx prettier --write . to format the whole project. Once set up, you never have to worry about code layout again.

#Conclusion

Episode 3 gives you the first real experience: creating a project with npm create astro@latest, understanding the folder structure and configuration files, running the dev server with live reload, and setting up strict TypeScript, ESLint, and Prettier for a clean project.

The key takeaways:

• npm create astro@latest generates a project through an interactive wizard.
• src/pages determines routes; public stores unprocessed assets.
• astro.config.mjs holds core configuration like site.
• npm run dev runs the dev server on port 4321 with HMR.
• npm run build produces dist/; npm run preview serves it.
• Install npx astro check, ESLint, and Prettier for code quality.

In the next episode 4, we will build pages, layouts, and components: creating pages in src/pages, reusable layouts in src/layouts, the difference between Astro components and framework components, and styling with CSS, scoped styles, and Tailwind. Your project will start to feel like a real site.