Skip to main content

Installation

The quickest way to a working site is to copy the starter example, which has all of this done. This page is the manual route: adding the theme to a project you create yourself, or to an existing Astro project.

Create the project

The theme isn’t published to npm; it’s installed straight from a tagged release of its public Git repository, with pnpm. Start with a package.json that declares the project as an ES module and gives you the usual Astro scripts:

{
  "name": "my-site",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "typecheck": "astro check"
  }
}

Next to it, a pnpm-workspace.yaml that tells pnpm which install scripts may run. Without it, the first install stops with “Ignored build scripts”:

allowBuilds:
  esbuild: true
  sharp: false

esbuild needs its postinstall to fetch the platform-specific binary. sharp is set to false because its install script falls through to a from-source build when a system libvips is present (macOS with Homebrew, for instance), and the prebuilt @img/sharp-* platform binary works at runtime regardless.

Install the package

Find the latest tag on the tags page and pin it exactly. Install it alongside the required peer dependencies:

pnpm add astro "git+https://github.com/ANUcybernetics/astro-theme-university.git#vX.Y.Z" @astrojs/mdx sharp pagefind lightningcss @iconify-json/iconoir
pnpm add -D @astrojs/check "typescript@^6"

The theme requires Astro ^7.0.0. @astrojs/mdx is needed so Astro can resolve the renderer entry point from your project root; the theme auto-registers the integration at build time. lightningcss is required because the theme configures Vite’s CSS transformer to use it; Vite resolves that package from your project root, not from inside the theme. @iconify-json/iconoir ships the iconoir icon set; astro-icon resolves iconify-set packages from the consumer’s package.json (not the theme’s), so the set has to live as a direct dep. pagefind builds the on-site search index after each build; search is on by default and the build fails if the binary is missing, so it’s only optional if you pass search: false. sharp is Astro’s image service, which the theme’s Card and Hero components use to encode local images. The theme’s interactive controls use native browser APIs and add no UI-framework dependency.

@astrojs/check and typescript are what pnpm typecheck runs. TypeScript stays on 6.x for now: astro check relies on a programmatic API the native TypeScript 7 compiler doesn’t ship yet.

Upgrading later is a deliberate edit: change the tag in package.json and run pnpm install. pnpm never moves a git dependency on its own, which is what makes an exact tag a reproducible pin.

Add the integration

Register the theme integration in your Astro config:

// astro.config.ts
import { defineConfig } from "astro/config";
import universityTheme from "astro-theme-university";

export default defineConfig({
  site: process.env.SITE_URL,
  base: process.env.BASE_PATH,
  integrations: [universityTheme()],
});

The theme integration automatically:

The theme is framework-free. If you’re coming from an older template that installed Svelte only for the theme, remove svelte, @astrojs/svelte, svelte-check, and the explicit svelte() integration; keep a framework only when your own components use it.

Create your first page

Add a tsconfig.json that extends Astro’s strict preset (this is what resolves imports like astro-theme-university/layouts/BaseLayout.astro):

{
  "extends": "astro/tsconfigs/strict"
}

Then use the theme’s BaseLayout in any Astro page:

---
// src/pages/index.astro
import BaseLayout from "astro-theme-university/layouts/BaseLayout.astro";
---

<BaseLayout title="My site">
  <h1>Welcome</h1>
  <p>This page uses the theme's BaseLayout.</p>
</BaseLayout>

pnpm build produces a static site in dist/ after running the accessibility and link checks.

The next step is to configure your site with a name and navigation links.