Explore More
🚀 Astro + Vue in Docker: A Modern Full-Stack Setup
This guide will show you how to create, develop, and deploy a modern Astro static site (with optional Vue components) using Docker, Yarn 4+, and best practices.
Official Astro docs:
1. Prerequisites
- Node.js installed locally (18+ recommended).
- Docker installed (Get Docker)
- Yarn (Berry / v4) will be managed by Corepack (included with Node 16+)
2. Creating a New Astro Project
# Start a new Astro project (official wizard)
npm create astro@latest
# OR, using Yarn
yarn create astro- Follow prompts for starter/template, name, and integrations (e.g., select Vue if you want Vue SFCs).
You'll get a project tree like this:
your-project/
├─ src/
│ ├─ pages/
│ ├─ components/
│ └─ ...
├─ public/
├─ package.json
└─ ...3. Add Vue Support for Astro (Optional)
Inside your project:
# Add Vue integration (if not already selected)
yarn add @astrojs/vue vueEdit astro.config.mjs:
import { defineConfig } from "astro/config";
import vue from "@astrojs/vue";
export default defineConfig({
integrations: [vue()],
});Adding a Vue Component to Your Astro Site
Here's an example Vue component (src/components/ExampleComponent.vue) you can use in your Astro site:
＜!-- src/components/ExampleComponent.vue —＞
＜template＞
＜div＞
＜p＞The counter is at: ＜strong＞{{ count }}＜/strong＞＜/p＞
＜button @click="count++"＞Increment＜/button＞
＜button @click="count—" style="margin-left: 0.5em;"＞Decrement＜/button＞
＜/div＞
＜/template＞
＜script setup＞
import { ref } from 'vue'
const count = ref(0)
＜/script＞
＜style scoped＞
button {
padding: 0.4em 1em;
font-size: 1em;
border-radius: 6px;
border: 1.5px solid #00ffc3;
background: #191a22;
color: #00ffc3;
margin-top: 0.5em;
cursor: pointer;
transition: border-color 0.2s, color 0.2s;
}
button:hover {
color: #ff2ed2;
border-color: #ff2ed2;
}
＜/style＞How to Use a Vue Component in Astro
In your Astro page (for example, src/pages/index.astro):
---
import ExampleComponent from '../components/ExampleComponent.vue';
---
<html lang="en">
<body>
<h1>Astro + Vue Example</h1>
<ExampleComponent client:visible />
</body>
</html>NOTE: The client:visible directive tells Astro to hydrate the Vue component on the client side when it appears in the viewport. If you want always-on interactivity instead, you can also use client:load.
4. Recommended Yarn Setup (PnP)
To optimize Yarn's performance and configuration for your Astro project, it's recommended to create a .yarnrc.yml file in your project root with the following content:
nodeLinker: pnpWhat is Yarn PnP?
Yarn PnP (Plug 'n' Play) is a package management strategy that replaces the traditional node_modules directory with a more efficient and optimized approach.
Benefits of Yarn PnP:
- Faster installation: Yarn PnP is significantly faster than traditional package installation methods.
- No node_modules directory: By not creating a node_modules directory, Yarn PnP reduces disk usage and avoids the overhead of maintaining a large directory tree.
- Smaller images: When building Docker images, Yarn PnP's optimized package management results in smaller image sizes, which can lead to faster deployment and reduced storage costs.
Why is Yarn PnP recommended for Astro?
By using Yarn PnP with Astro, you can take advantage of faster installation times, reduced disk usage, and smaller Docker image sizes. This optimized setup helps streamline your development and deployment workflow, making it an ideal choice for Astro projects.
5. Basic Astro Routing
Astro uses a file-based routing system, which allows you to create pages and routes by simply adding files to your project directory. Here's how it works:
How Routing Works
- Every file in src/pages/ becomes a route: Astro automatically generates routes for your application based on the files in the src/pages/ directory.
- File name = Route path: The file name of each page component is used to determine its corresponding route path.
Astro Routing Examples
- src/pages/index.astro → / (homepage)
- src/pages/about.astro → /about
- src/pages/blog/post.astro → /blog/post
- src/pages/nested/routes/example.astro → /nested/routes/example
Benefits of File-Based Routing
- Instant page creation: With Astro's file-based routing, you can create new pages and routes instantly by adding a new file to the src/pages/ directory.
- Simplified routing: File-based routing eliminates the need to manually configure routes, making it easier to manage and maintain your application's routing.
Using Astro's File-Based Routing
To take advantage of Astro's file-based routing, simply create new files in the src/pages/ directory, and Astro will automatically generate the corresponding routes for your application. For more information, see Astro's official documentation on routing.
6. Develop Astro Locally (with Docker & Yarn 4+)
Docker Compose Astro Service for Development
Sample service in docker-compose.yml:
services:
astro_dev:
image: node:24-alpine3.22
container_name: astro_dev
working_dir: /app
command: sh -c "yarn install && yarn dev —host"
environment:
- NODE_ENV=development
volumes:
- ./astro:/app
ports:
- "8092:4321"- This mounts your local /astro folder into the container for hot reloads.
- Runs the Astro dev server at localhost:8092.
Start the Astro Docker Container:
docker compose up astro_dev7. Astro Production Build & Deployment
Here's the Astro Dockerfile (Dockerfile.astro) file for production:
FROM node:24-alpine3.22
WORKDIR /app
# Enable Yarn 4+ via Corepack
RUN corepack enable && corepack prepare yarn@stable —activate
COPY . .
RUN yarn install —production —immutable
RUN yarn build
EXPOSE 8080
CMD ["npx", "serve", "dist", "—listen", "8080"]- yarn build creates a static site in /dist
- npx serve serves it efficiently
Corepack is needed for Astro in Docker because of Yarn.
Corepack is a package manager that allows you to use the latest versions of package managers like Yarn and npm without having to install them globally on your system.
In this case, the Astro Dockerfile uses Corepack to enable and prepare Yarn, specifically version 4 and above, for use in the Docker container. This is done with the following commands:
RUN corepack enable && corepack prepare yarn@stable —activateBy using Corepack, the Dockerfile can ensure that Yarn is installed and configured correctly within the container, without relying on a globally installed version of Yarn. This approach provides more control over the version of Yarn being used and helps to ensure consistency across different environments.
In the context of the provided Dockerfile, Corepack is used to enable Yarn 4+ support, which is likely a requirement for the Astro project being built and deployed.
Astro Production Docker Compose Service
Finally, you can just add context: and dockerfile: YAML fields, in the docker-compose.prod.yml file, under the astro_prod service:
services:
astro_prod:
build:
context: ./astro
dockerfile: Dockerfile.astro
container_name: astro_prod
ports:
- "8092:8080"Here's the docker compose command to build and spin up the production container:
docker compose -f docker-compose.prod.yml up —build8. Astro File & Folder Structure
Here is a recommended layout for the Docker/Astro/Vue project:
docker-compose.yml
astro/
├── .astro/ # Astro's cache (ignore in git)
├── .dockerignore
├── .gitignore
├── .yarnrc.yml
├── astro.config.mjs
├── Dockerfile.astro
├── package.json
├── public/ # Static files (favicon, images, etc)
├── src/
│ ├── assets/
│ ├── components/
│ │ └── ExampleComponent.vue
│ ├── layouts/
│ ├── pages/
│ │ ├── index.astro
│ │ └── about.astro
│ └── styles/
├── tsconfig.json
└── yarn.lockNOTE The docker-compose.yml file should be one level up from astro/. Adjust as needed.
9. Ignore Files (Best Practice)
.gitignore (in /astro):
node_modules/
.pnp.*
.yarn/*
!.yarn/releases
!.yarn/plugins
!.yarn/sdks
!.yarn/versions
dist/
.env
*.log.dockerignore (in /astro):
node_modules
.pnp.*
.yarn/*
!.yarn/releases
!.yarn/plugins
!.yarn/sdks
!.yarn/versions
dist
.git
.env10. Key Tips & References
Astro official getting started:
Astro Routing:
👉 Astro Routing Docs
Astro + Vue guide:
👉 Astro + Vue
Yarn PnP:
👉 Yarn Plug'n'Play
Summary Workflow
1. Install Node.js & Docker on host
2. Create Astro project: npm create astro@latest
3. Add Vue if you want Vue components: yarn add @astrojs/vue vue
This is optional unless your site needs interactive Vue SFCs.
4. Set up Yarn 4+ with PnP: .yarnrc.yml
5. Run dev in Docker: mounts code for live editing
6. Build & run prod in Docker: clean, static, fast
7. Use src/pages/ for instant file-based routing
Conclusion
Astro makes it simple to create blazing-fast, modern websites with clean file-based routing and support for your favorite frameworks—including Vue. By pairing Astro with Docker, you get a portable, production-ready development environment that's easy to share and deploy. Whether you're starting your first Astro website, looking for an Astro website template, or want to integrate Astro with Vue using best practices, this approach is flexible and future-proof. Don't forget to explore the official Astro docs and experiment with Astro Docker images, Astro Vue components, and more for your next project!