On this page
Astro is a web framework for content-focused sites. You write familiar HTML, CSS, JavaScript, and TypeScript in components, and Astro turns pages into static HTML by default. Browser JavaScript is added only when you deliberately need it.
That makes Astro a useful next step after learning the web’s foundations: it improves project organization without hiding the HTML that visitors receive.
Check Node.js before creating the project
Astro 7 requires Node.js 22.12.0 or newer. In a terminal, run:
node --version
npm --versionThe first command should print a Node version at or above v22.12.0. The npm version can vary with your Node installation.
If node is not recognized or the version is too old, install a supported Node release using the method recommended for your operating system. Do not copy a project command repeatedly until the runtime requirement is fixed.
Create a minimal Astro project
Move to the folder that should contain your new project—not inside another project—then run the official setup command:
npm create astro@latestThe setup wizard asks where to create the project. Enter first-astro-site. Choose the minimal starter when prompted, install dependencies, and initialize Git only if you want a new local repository.
Then move into the new directory:
cd first-astro-siteThe @latest tag asks npm for the current stable project creator. It avoids putting an already outdated version number into a beginner tutorial.
Understand the important folders
A minimal project has a shape similar to this:
first-astro-site/
├── public/
├── src/
│ └── pages/
│ └── index.astro
├── astro.config.mjs
├── package.json
└── tsconfig.jsonsrc/pages/controls routes.src/pages/index.astrobecomes the homepage.public/stores files Astro should copy without processing, such as a simple favicon or robots file.astro.config.mjsholds project-wide Astro configuration.package.jsonlists scripts, packages, and project metadata.tsconfig.jsonconfigures TypeScript checking.
As the site grows, you can add src/components/ for reusable interface pieces, src/layouts/ for shared page structures, and content collections for validated Markdown or MDX.
Start the development server
Run:
npm run devAstro prints a local development address in the terminal. Open that address in a browser. When the default port is available, the address ends with :4321. The development server watches your files and refreshes the page after saved changes.
Stop the server with Ctrl+C when you need the terminal for another command.
Edit the homepage
Replace the starter page with this small Astro component:
---
const pageTitle = "My first Astro website";
const skills = ["HTML", "CSS", "Astro"];
---
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width" />
<meta name="description" content="A small website built while learning Astro." />
<title>{pageTitle}</title>
</head>
<body>
<main>
<p class="eyebrow">Learning in public</p>
<h1>{pageTitle}</h1>
<p>I am turning web fundamentals into something I can share.</p>
<h2>Skills used</h2>
<ul>
{skills.map((skill) => <li>{skill}</li>)}
</ul>
</main>
</body>
</html>
<style>
:global(*) {
box-sizing: border-box;
}
:global(body) {
margin: 0;
font-family: system-ui, sans-serif;
background: #f4f6ff;
color: #17203a;
}
main {
width: min(42rem, calc(100% - 2rem));
margin-inline: auto;
padding-block: 5rem;
}
.eyebrow {
color: #3946d6;
font-weight: 700;
letter-spacing: 0.08em;
text-transform: uppercase;
}
h1 {
font-size: clamp(2.25rem, 8vw, 4.5rem);
line-height: 1;
}
li + li {
margin-top: 0.5rem;
}
</style>Astro component frontmatter is the section between the two --- fences at the top. It runs while Astro renders the page. Here it prepares a title and an array, then the template uses those values in braces.
The skills.map() expression creates one <li> for each skill. The style block is scoped to this component by default. The :global() selectors are intentional because html and body are document-level elements.
Build the production files
Stop the development server if it is using your terminal, then run:
npm run buildAstro compiles the pages and writes the static result to dist/ by default. A successful build confirms that the page can be generated; larger projects commonly add astro check as a separate type-checking step. You can inspect the production build locally with:
npm run previewThe preview command is for a final local check. Continue using npm run dev while editing because it gives the faster development experience.
Common mistakes
Creating the project inside another project. Check pwd or your terminal’s current path before starting. Nested package files are confusing.
Running commands from the parent folder. npm run dev must run where the new project’s package.json exists.
Removing the frontmatter fences. The opening and closing --- are part of an Astro component’s syntax, even when the frontmatter is empty.
Treating public files like imported source assets. Files in public/ are copied as-is. Source assets that Astro should process belong under src/.
Assuming every component sends JavaScript. Astro components render to HTML and CSS unless you add a client-side script or hydrate a supported UI-framework component.
Practice
Practice: make the page yours
Change the title and introductory text. Add a fourth skill to the array and confirm that another list item appears. Then add a link to a real page you find useful, using descriptive link text rather than “click here.”
What to learn next
Before extracting the document shell, make sure its regions use meaningful semantic HTML. You can also practice the underlying markup and responsive CSS in the personal landing-page project. Then turn one repeated interface block into a component with typed props and add a Markdown content collection. Astro’s project structure guide is the best reference as your first site gains more folders.