Installation

What You’ll Achieve

If you are searching for an AstroAnimate installation guide , this page solves the exact setup task: install AstroAnimate correctly, confirm compatibility, and run a working first import in your Astro app.

By the end of this page, you will:

  • Install AstroAnimate using the correct package name
  • Verify Astro version compatibility before implementation
  • Add a component import in a real `.astro` page
  • Run checks to validate install quality before shipping
  • Fix common install-time errors quickly

This page is designed for developers who want a practical result, not a generic overview.

Prerequisites / Requirements

Before installing, confirm the following:

  • You already have an Astro project.
  • Your project uses a compatible Astro version (` ^4.0.0 || ^5.0.0 || ^6.0.0`).
  • You can run npm commands from your project root.
  • You have write access to 'package.json' and lockfile updates.

Step-by-Step Guide

Step 1: Install the package

Run this command from your Astro project root:

bash 
npm install @astroanimate/core

This installs the official AstroAnimate package.

Step 2: Import your first component

Use a direct component import for a clear first validation: 

---
import FadeIn from "@astroanimate/core/FadeIn";
---

<main>
  <FadeIn enhance direction="up" distance=20 once>
    <h1>AstroAnimate is installed</h1>
  </FadeIn>
</main>

Step 3: Optional: import from root exports

AstroAnimate also exposes root exports. If your team prefers grouped imports: 

---
import { FadeIn, SlideIn, TextRotate } from "@astroanimate/core";
---

Use this style when you want centralized imports in shared UI files.

Step 4: Run install quality checks

After installation, run these checks: 

npm run build
npm run typecheck
npm run lint
npm run test

Why this matters:

  • Build confirms bundling integrity.
  • Typecheck catches integration and TS issues early.
  • Lint keeps implementation consistent.
  • Tests reduce regression risk before release.

Expected result: all checks pass before you proceed to larger adoption in your app.

Step 5: Verify in development mode

Run your local dev server and open your page: 

npm run dev

Validation checklist:

  • The page renders with no module resolution errors.
  • Imported component appears correctly.
  • If `enhance` is used, behavior is visible in browser (unless reduced-motion preferences suppress animations).

Notes

  • AstroAnimate is an Astro-native component library; use it inside .astro workflows.
  • Use the exact package name @astroanimate/core.
  • Keep import paths consistent across your codebase (subpath or root-export style).
  • Some behavior is enhancement-based. If expected interaction is not visible, confirm component props and reduced-motion settings.
  • For production rollout, run quality checks in CI, not only locally.

FAQ (Developer Questions)

Is AstroAnimate only for Astro?
Yes. It is fully built for the Astro ecosystem.
How do I install AstroAnimate in Astro?
Run: npm install @astroanimate/core. Then import a component in an .astro file and run your app.
Which Astro versions are supported by AstroAnimate?
AstroAnimate supports Astro ^4.0.0 || ^5.0.0.
Should I use subpath imports or root imports?
Both are supported. Use subpath imports (for example @astroanimate/core/FadeIn) for explicit per-component usage, or root imports (@astroanimate/core) for grouped style conventions.
Why does my component render but not animate as expected?

Common causes:

  • Enhancement-based behavior not enabled (when required by component usage)
  • Reduced-motion OS/browser setting active
  • Incorrect props or test condition (for example, scroll-trigger behavior not yet in viewport)

Start by validating one known working example, then scale.

Can I ship AstroAnimate to production immediately after install?
Yes, if your use case matches current components and your quality checks pass. Recommended flow: install → first render → run checks → QA in target browsers/devices → deploy.
PREVIOUS Introduction NEXT Quick Start

Follow us: