# astropress

> Astro-first WordPress development framework with a Composer-managed local WordPress runtime.

Latest version **0.1.52** (published 2026-09-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install astropress
pnpm add astropress
yarn add astropress
bun add astropress
```

Provides the command `astropress`.

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.52 |
| Published | 2026-09-25 |
| First published | 2026-07-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=20 |
| Dependencies | 2 |
| Unpacked size | 318.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Didair |
| Maintainers | aekstrom |
| Keywords | wordpress, astro, vite, headless, php, composer |

## Links

- npm: https://www.npmjs.com/package/astropress
- Repository: https://github.com/didair/astropress
- Homepage: https://github.com/didair/astropress#readme
- Issues: https://github.com/didair/astropress/issues
- npm.io page: https://npm.io/package/astropress

## Dependencies (2)

- [vite](https://npm.io/package/vite.md) ^8.1.1
- [astro](https://npm.io/package/astro.md) ^7.0.6

## Alternatives

- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads

## Recent versions

- 0.1.52 (latest) — 2026-09-25
- 0.1.51 — 2026-09-03
- 0.1.49 — 2026-07-30
- 0.1.48 — 2026-07-29
- 0.1.47 — 2026-07-29
- 0.1.46 — 2026-07-29
- 0.1.45 — 2026-07-28
- 0.1.43 — 2026-07-28
- 0.1.42 — 2026-07-28
- 0.1.41 — 2026-07-27

## README

# AstroPress

AstroPress is an Astro-first WordPress development framework.

One entrypoint for everything you need, no fuzz and no magic.

## Requirements

- Node.js 20+
- PHP 8.3+
- Composer
- a MySQL or MariaDB server

## Get started

```bash
mkdir my-site
cd my-site
npm init -y
npx astropress init
cp .env.example .env
```

`astropress init` creates the starter files, adds the needed package dependencies, and runs install.

Edit `.env` with your database credentials, run `npm run dev`, wait for the initial configuration and then open:

```txt
http://localhost:3000
```

If the database is empty, go to `/wp-admin/` and complete the WordPress installer.

## Commands

```bash
npm run dev      # Start the local AstroPress runtime
npm run build    # Build Astro + WordPress assets for deployment
npm run start    # Start the built AstroPress runtime
npm run doctor   # Check PHP, Composer, WordPress, config, and environment
npm run types    # Generate WordPress-derived TypeScript types
npm run check    # Run Astro type checking
npm run upgrade  # Upgrade AstroPress-managed project files
npx astropress composer install  # Run Composer in the project
npx astropress wp plugin list    # Run WP-CLI when installed
```

For internal runtime diagnostics:

```bash
npm run dev -- --verbose
```

## Upgrading

Upgrade an AstroPress project from inside the project with:

```bash
npx astropress@latest upgrade
```

The command updates the local `astropress` dependency, refreshes AstroPress-owned WordPress runtime files such as the bridge mu-plugin and placeholder theme, and overwrites starter support files with timestamped `.old` backups. Use `--dry-run` to preview changes first and `--force-config` if you also want to overwrite `astropress.config.ts`.

## Production build and start

The first deployable AstroPress runtime mirrors development mode without watchers, HMR, or the dev toolbar. Build optimized Astro and WordPress-side assets with:

```bash
npm run build
```

Then start the built runtime:

```bash
npm run start
```

`astropress build` validates the project, installs Composer dependencies when needed, refreshes the generated WordPress bridge/theme files, builds block/plugin assets in production mode, runs `astro build`, and writes `.astropress/deploy.json`.

`astropress start` starts the local WordPress/PHP runtime, starts Astro's built preview/server command, and puts the same AstroPress proxy in front of both processes. WordPress internals go to WordPress; public frontend routes go to Astro:

```txt
/wp-admin/*      -> WordPress
/wp-login.php    -> WordPress
/wp-json/*       -> WordPress
/wp-content/*    -> WordPress files, including uploads
/wp-includes/*   -> WordPress files
/*.php           -> WordPress
/*               -> Astro
```

For this first production shape, WordPress owns media. AstroPress serves WordPress-origin `/wp-content/uploads` URLs and does not sync uploads to a CDN, rewrite media URLs, or run WordPress media through Astro's image pipeline.

For dynamic WooCommerce/cart/account pages, render with `renderWordPressPage({ cache: false })` and keep those routes uncached at any outer proxy/CDN layer.

## Folder structure

```txt
my-site/
  astro.config.mjs
  astropress.config.ts
  composer.json
  .env

  .astropress/
    types.d.ts             # generated WordPress types

  src/
    live.config.ts
    templates/             # optional template overrides

  wordpress/
    public/              # Composer-installed WordPress core
    content/
      mu-plugins/        # AstroPress bridge is generated here
      themes/            # AstroPress placeholder theme is generated here
      plugins/
      uploads/
```

## Templates

AstroPress ships default templates from the package. Create files in `src/templates` only when you want to override them.

Examples:

```txt
src/templates/pages/front-page.astro
src/templates/layouts/Base.astro
src/templates/pages/page-about.astro
src/templates/posts/single.astro
src/templates/posts/archive.astro
src/templates/taxonomies/category.astro
src/templates/search.astro
src/templates/404.astro
```

Template props are typed by importing the matching generated type as Astro's `Props` type:

```astro
---
import type { WpPageTemplateProps as Props } from 'wp-types';

const { title, content, item, route, Layout } = Astro.props;
---

<Layout {...Astro.props}>
  <h1>{title}</h1>
  <div set:html={content} />
</Layout>
```

Available generated types include `WpPageTemplateProps`, `WpSingleTemplateProps`,
`WpArchiveTemplateProps`, `WpSearchTemplateProps`, and `WpTaxonomyTemplateProps`.
Custom post types and taxonomies can be narrowed with a generic, such as
`WpSingleTemplateProps<'product'>`.

`npm run types` writes these project-specific types to `.astropress/types.d.ts`.
AstroPress exposes that generated file through the `wp-types` alias.

## WordPress data

AstroPress uses Astro Live Collections for WordPress data:

```ts
import { getLiveCollection, getLiveEntry } from 'astro:content';

const route = await getLiveEntry('routes', { path: '/' });
const posts = await getLiveCollection('posts', { page: 1, perPage: 10 });
const menu = await getLiveEntry('menus', { location: 'primary' });
```

After `npm run dev` or `npm run check`, collection names and filters should have TypeScript completion.

## Menus

Register WordPress menu positions in `astropress.config.ts`:

```ts
export default defineConfig({
  wordpress: {
    menus: {
      primary: 'Primary menu',
      footer: 'Footer menu',
    },
  },
});
```

Then assign menus to those locations in WordPress admin and fetch them by location:

```ts
import { getMenuByLocation } from 'astropress/wordpress';

const menu = await getMenuByLocation('primary');
```

## WordPress hooks in Astro

Astro templates can ask the internal WordPress runtime to render real WordPress actions and filters during SSR:

```astro
---
import { createHooks } from 'astropress/wordpress';

const hooks = createHooks(Astro.props);
const head = await hooks.action('wp_head');
const content = await hooks.filter('the_content', Astro.props.content);
---

<Fragment set:html={head.rendered} />
<article set:html={content.value} />
```

The default layout renders `wp_head` after WordPress has finished loading. When
that output contains a document title (for example from Yoast SEO), it owns the
title; the layout's content-title fallback is emitted only when WordPress does
not provide one. Custom layouts should follow the same single-owner pattern to
avoid duplicate titles or SEO metadata.

## Blocks and plugin assets

AstroPress discovers block metadata from `src/blocks/**/block.json` and bundles WordPress-side JS/TS and optional CSS.

```txt
src/blocks/hero/block.json
src/blocks/hero/edit.tsx
src/blocks/hero/style.css # optional
```

---
_Source: https://npm.io/package/astropress · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._