# WordPressify

> Full documentation for WordPressify.

---

# Introduction

> WordPressify is a development tool that simplifies WordPress theme and plugin creation.

Source: https://wordpressify.co/

# Introduction

WordPressify is a development tool that simplifies WordPress theme and plugin creation.

- **Live reload**: Watches for file changes and instantly reloads your browser via BrowserSync.
- **Local database**: Includes a pre-configured MariaDB database, ready to use.
- **Modern CSS**: Preprocess styles with PostCSS, with autoprefixing built in. Sass can be added as an [optional setup](/postcss-sass).
- **Modern JavaScript**: Write ES6+ with Babel, bundled automatically.
- **Docker-based**: Runs everything in containers, so the only dependency is Docker.

## Quick Start

```bash
npx wordpressify
npm run start
```

Once the containers are up, your site is available at [http://localhost:3010](http://localhost:3010).

Optionally, rename `.env_example` to `.env` before starting to customize the theme name and port. See [Start Project](/start-project) for details.

<Callout type="info">
WordPressify works on macOS, Windows, and Linux. The only prerequisite is Docker.
</Callout>

<Columns cols={2}>
  <Card title="Install Docker" icon="Container" href="/install-docker">
    The only dependency you need.
  </Card>
  <Card title="Start Project" icon="Rocket" href="/start-project">
    File structure, commands, and workflow.
  </Card>
</Columns>

---

# Install Docker

> Docker container overview and installation instructions for WordPressify.

Source: https://wordpressify.co/install-docker

# Install Docker

Docker is the only dependency required to run WordPressify. It packages the WordPress environment, database, and build tools into containers so everything works the same on any OS.

<Card title="Download Docker Desktop" icon="Download" href="https://www.docker.com/products/docker-desktop/">
  Choose your operating system and install Docker Desktop.
</Card>

## Verify Installation

After installing, confirm the Docker daemon is running:

```bash
docker info
```

This is the same check WordPressify runs before executing any Docker command. If it prints server information, you are ready to go. If it fails, open Docker Desktop and wait for it to finish starting; if the command is not found at all, restart your terminal or check the [troubleshooting](/troubleshooting) page.

<Card title="Next: Install WordPressify" icon="Rocket" href="/install-wordpressify">
  Install WordPressify via npm or from the repository.
</Card>

---

# Install WordPressify

> Install WordPressify from NPM or from the GitHub repository.

Source: https://wordpressify.co/install-wordpressify

# Install WordPressify

<Callout type="info">
Requires Node.js 12.20 or later. Docker must be installed and running before running WordPressify.
</Callout>

<Tabs>
  <TabContent title="From NPM">
    Create a new directory for your project and scaffold it:

    ```bash
    mkdir my-theme && cd my-theme
    npx wordpressify
    ```

    This copies the full file structure into your directory. There is no `npm install` step: dependencies are installed inside the Docker containers when they are first built.

    To skip the confirmation prompt, use the `-y` (or `--non-interactive`) flag:

    ```bash
    npx wordpressify -y
    ```
  </TabContent>
  <TabContent title="From Repository">
    Clone the repository from GitHub:

    ```bash
    git clone https://github.com/luangjokaj/wordpressify
    cd wordpressify
    ```

    Replace the root `package.json` with the one from the installer directory, then install dependencies:

    ```bash
    cp ./installer/package.json ./package.json
    npm install
    ```

    The installer's `package.json` contains the correct scripts and dependencies for development. The root one is for publishing the npm package.
  </TabContent>
</Tabs>

## Update an Existing Project

To update the core WordPressify files (Docker, build pipeline, configs) without touching your `src/` folder or dependencies:

```bash
npx wordpressify update
```

This overwrites infrastructure files like `docker-compose.yml`, `gulpfile.js`, Dockerfiles, and linting configs. It also updates the `scripts` section in your `package.json` while preserving your dependencies.

To skip the confirmation prompt, use the `-y` (or `--non-interactive`) flag:

```bash
npx wordpressify update -y
```

<Card title="Next: Start Project" icon="Rocket" href="/start-project">
  Set up your theme name and start the dev server.
</Card>

---

# Start Project

> File structure, theme naming, workflow commands, and production export for WordPressify.

Source: https://wordpressify.co/start-project

# Start Project

<Callout type="warning">
Make sure Docker is running before you start. WordPressify automatically checks for Docker and will show a clear error message if it is not active.
</Callout>

## File Structure

- **`src/theme/`** - Block theme files (HTML templates, `theme.json`, PHP).
- **`src/plugins/`** - Custom WordPress plugins.
- **`src/assets/css/`** - CSS stylesheets.
- **`src/assets/fonts/`** - Font files.
- **`src/assets/img/`** - Image assets.
- **`src/assets/js/`** - JavaScript files.

Configuration files, Docker files, and build scripts live in the project root.

## Change Theme Name

Rename `.env_example` to `.env` to customize your settings. Both variables have sensible defaults, so the `.env` file is optional if you are happy with the defaults:

```bash
# If you want to connect to BrowserSync on a different port. Default: 3010
PROXY_PORT=3010

# Theme name. Default: "wordpressify"
THEME_NAME=wordpressify
```

This name is used for the theme directory in WordPress and in the exported zip file.

## Start Workflow

<Steps>
  <Step title="Start the development server">
    <CodeTabs tabs={[{ label: "npm", code: "npm run start" }, { label: "Docker", code: "docker compose up" }]} />

    If Node.js is not installed locally, use the Docker command.

    Once the containers are up, your site is available at:

    - [http://localhost:3010](http://localhost:3010) - Development site with live reload (BrowserSync proxy, port configurable via `PROXY_PORT`).
    - [http://localhost:8080](http://localhost:8080) - Direct nginx access, without live reload.
    - [http://localhost:3001](http://localhost:3001) - BrowserSync UI, for debugging the proxy.
  </Step>
  <Step title="Rebuild environment">
    To rebuild with a fresh WordPress installation and clean database:

    <CodeTabs tabs={[{ label: "npm", code: "npm run rebuild" }, { label: "Docker", code: "docker compose down -v && docker compose build" }]} />
  </Step>
  <Step title="Add WordPress plugins">
    Place custom plugins in the `src/plugins/` directory. They are automatically copied into the WordPress plugins folder during the build.
  </Step>
  <Step title="Export for production">
    Generate optimized distribution files:

    <CodeTabs tabs={[{ label: "npm", code: "npm run export" }, { label: "Docker", code: "docker compose run --rm nodejs npm run prod" }]} />

    The theme is saved as a zip file in `dist/wordpressify.zip`.
  </Step>
</Steps>

## All Commands

| Command | Description |
|---------|-------------|
| `npm run start` | Start the development server (`docker compose up`). |
| `npm run build` | Rebuild the Docker images. Required after changing `gulpfile.js` or `package.json`. |
| `npm run rebuild` | Tear down containers and volumes, then rebuild. Gives you a fresh WordPress install and clean database. |
| `npm run delete` | Remove containers and volumes (`docker compose down -v`). Deletes the database. |
| `npm run export` | Build production distribution files into `dist/`. |
| `npm run export:backup` | Zip the entire `build/` directory (full WordPress install) into `backups/<date>.zip`. |
| `npm run lintcss` | Lint CSS files in `src/` with Stylelint. |

Every command that talks to Docker first checks that the Docker daemon is running and prints a clear error if it is not.

## Code Formatting and Linting

The project ships with pre-configured code quality tools:

- **Prettier** (`.prettierrc`) - Formats HTML, JavaScript, and CSS (2-space indent, double quotes, 80 character line width).
- **PHP CS Fixer** (`.php-cs-fixer.php`) - Enforces consistent PHP code style.
- **Stylelint** (`.stylelintrc`) - Lints CSS. Run it with `npm run lintcss`.

## Debugging with Xdebug

The WordPress container ships with Xdebug installed and configured (`config/php.ini`), listening on port 9003. Profiler and trace output, the Xdebug log, and the WordPress error log (`wp-errors.log`) are written to the `xdebug/` directory in your project root.

---

# PostCSS and Sass

> CSS preprocessing with PostCSS and Sass integration in WordPressify.

Source: https://wordpressify.co/postcss-sass

# PostCSS and Sass

<Tabs>
  <TabContent title="PostCSS">
    WordPressify uses PostCSS by default. You can add, remove, or swap plugins to build the exact CSS feature set you need.

    The plugin lists are defined in `gulpfile.js`:

    **Development plugins** (`pluginsListDev`):
    - partialimport
    - postcssPresetEnv
    - postCSSMixins
    - autoprefixer

    **Production plugins** (`pluginsListProd`):
    - partialimport
    - postcssPresetEnv
    - postCSSMixins
    - autoprefixer
    - cssnano (minification)

    ## Writing CSS

    The main CSS entry point is:

    ```bash
    src/assets/css/style.css
    ```

    This file contains the WordPress template header comment and imports for your stylesheets.
  </TabContent>
  <TabContent title="Sass">
    To use Sass instead of PostCSS, install the required packages:

    ```bash
    npm install sass gulp-sass
    ```

    Rename the entry point `src/assets/css/style.css` to `style.scss`, keeping the WordPress template header comment.

    Then update `gulpfile.js`. Add the imports and create the Sass compiler:

    ```diff
    import zip from "gulp-vinyl-zip";
    import cssnano from "cssnano";
    +import dartSass from "sass";
    +import gulpSass from "gulp-sass";

    const { series, dest, src, watch } = pkg;
    +const sass = gulpSass(dartSass);
    ```

    Update the `stylesDev` task:

    ```diff
    function stylesDev() {
    -  return src("./src/assets/css/style.css")
    +  return src("./src/assets/css/style.scss")
        .pipe(plumber({ errorHandler: onError }))
        .pipe(sourcemaps.init())
    -    .pipe(postcss(pluginsListDev))
    +    .pipe(sass({ includePaths: "node_modules" }).on("error", sass.logError))
        .pipe(sourcemaps.write("."))
        .pipe(dest("./build/wordpress/wp-content/themes/" + themeName))
        .pipe(browserSync.stream({ match: "**/*.css" }));
    }
    ```

    Update the CSS watcher to monitor `.scss` files:

    ```diff
      const watcherCSS = watch(
    -    ["./src/assets/css/**/*.css", "!./**/.DS_Store"],
    +    ["./src/assets/css/**/*.scss", "!./**/.DS_Store"],
        watchOptions,
      );
    ```

    <Callout type="info">
    `gulpfile.js` is baked into the Node.js Docker image, so after these changes run `npm run build` before starting the server. See [Build Changes](/build-changes).
    </Callout>

    Update the `stylesProd` task:

    ```diff
    function stylesProd() {
    -  return src("./src/assets/css/style.css")
    +  return src("./src/assets/css/style.scss")
        .pipe(plumber({ errorHandler: onError }))
    -    .pipe(postcss(pluginsListProd))
    +    .pipe(sass({ includePaths: "node_modules" }).on("error", sass.logError))
        .pipe(dest("./dist/themes/" + themeName));
    }
    ```
  </TabContent>
</Tabs>

## Linting

CSS is linted with [Stylelint](https://stylelint.io/), configured in `.stylelintrc` in the project root. Run it with:

```bash
npm run lintcss
```

This runs Stylelint against all CSS files in `src/` inside the Node.js container.

---

# Images and Fonts

> Managing image and font assets in your WordPressify theme.

Source: https://wordpressify.co/images-fonts

# Images and Fonts

## Images

Store theme image assets in:

```bash
src/assets/img/
```

These files are automatically copied to the build directory and included in the production export. Deleting a file from `src/assets/` also removes it from the build, so the two stay in sync.

<Callout type="info">
Keep only essential assets (icons, logos, SVGs) in your theme directory. Use the WordPress Media Library for content images like photos and illustrations. This keeps the theme lightweight and faster to deploy.
</Callout>

To reference an image in your PHP templates:

```php
<img src="<?php echo get_template_directory_uri(); ?>/img/logo.svg" alt="Logo">
```

## Fonts

Store custom font files in:

```bash
src/assets/fonts/
```

They are copied to a `fonts/` folder at the root of the compiled theme.

The default theme registers its bundled fonts (Inter and Fira Code) in `src/theme/theme.json`, which is the recommended approach for block themes:

```json
{
  "name": "Inter",
  "slug": "inter",
  "fontFamily": "Inter, sans-serif",
  "fontFace": [
    {
      "src": ["file:./fonts/inter/Inter-VariableFont_slnt,wght.woff2"],
      "fontWeight": "200 800",
      "fontStyle": "normal",
      "fontFamily": "Inter"
    }
  ]
}
```

Add entries like this under `settings.typography.fontFamilies` in `theme.json`.

Alternatively, load fonts with `@font-face` in your CSS. Note that the compiled `style.css` sits at the theme root, next to the `fonts/` folder, so the path is relative to it:

```css
@font-face {
  font-family: "CustomFont";
  src: url("fonts/CustomFont.woff2") format("woff2");
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}
```

For Google Fonts or other externally hosted fonts, enqueue them in your theme's `functions.php` instead of bundling the files locally.

---

# JavaScript

> ES6 JavaScript support with Babel in WordPressify.

Source: https://wordpressify.co/javascript

# JavaScript

WordPressify supports ES6+ JavaScript through Babel. You can use modern syntax like arrow functions, destructuring, and modules, and Babel compiles it down for browser compatibility.

## File Location

Place your JavaScript files in:

```bash
src/assets/js/
```

WordPressify watches this directory for changes and bundles all files into a single `footer-bundle.js`, which is loaded in the footer of every page.

## How Bundling Works

The bundling is configured in `gulpfile.js`. Two bundles are produced:

- **`footer-bundle.js`** - Your code from `src/assets/js/`, transpiled with Babel.
- **`header-bundle.js`** - Third-party libraries listed in the `headerJS` array (jQuery by default), concatenated without Babel.

During development, source maps are generated so you can debug your original source in the browser's DevTools. In production builds, the output is minified.

## Formatting

A Prettier config (`.prettierrc`) ships with the project for formatting HTML, JavaScript, and CSS: 2-space indent, double quotes, and an 80 character line width.

## Configuration

To control which scripts are loaded in the header vs footer, or to change Babel settings, see the [External Libraries](/external-libraries) page and the `gulpfile.js` in your project root.

---

# External Libraries

> Incorporating external JavaScript libraries into your WordPressify project.

Source: https://wordpressify.co/external-libraries

# External Libraries

You can add any npm package to your WordPressify project and include it in the build.

## Example: Adding a Library

Install the package:

```bash
npm install <package-name>
```

Then add it to the appropriate bundle array in `gulpfile.js`. jQuery ships preinstalled and is already included in the header bundle by default:

```javascript
/* -------------------------------------------------------------------------------------------------
Header & Footer JavaScript Bundles
-------------------------------------------------------------------------------------------------- */
const headerJS = [ './node_modules/jquery/dist/jquery.js' ];
const footerJS = [ './src/assets/js/**' ];
```

## Header vs Footer Scripts

- **`headerJS`** - Loaded in the `<head>` before the DOM renders. Use this for libraries that other scripts depend on immediately.
- **`footerJS`** - Loaded at the end of `<body>` after the DOM is ready. Only footer scripts are processed through Babel (ES6 support). Your custom code should go here.

You can configure Babel to also process header scripts by modifying the corresponding gulp task in `gulpfile.js`.

<Callout type="warning">
`gulpfile.js` and `package.json` are baked into the Node.js Docker image, so changes require an image rebuild. Stop the server with `CTRL/CMD+C`, run `npm run build`, then `npm run start`. See [Build Changes](/build-changes).
</Callout>

---

# Build Changes

> Which files require a container restart or an image rebuild when modified in WordPressify.

Source: https://wordpressify.co/build-changes

# Build Changes

Files in `src/` are watched and applied instantly via live reload. Configuration and build files are not: depending on how they are wired into Docker, changing them requires either restarting the containers or rebuilding the images.

## Restart Containers

These files are mounted or read at container startup. Stop the running process with `CTRL/CMD+C` and start again, using the Docker command if Node.js is not installed locally:

| File | Description |
|------|-------------|
| `config/` | Nginx & PHP configurations |
| `.env` | Environment variables |
| `docker-compose.yml` | Docker Compose configuration |

<CodeTabs tabs={[{ label: "npm", code: "npm run start" }, { label: "Docker", code: "docker compose up" }]} />

## Rebuild Images

These files are baked into the Docker images at build time, so a restart alone is not enough:

| File | Description |
|------|-------------|
| `gulpfile.js` | Gulp configuration |
| `package.json` | Node.js packages |
| `.stylelintrc` | Stylelint configuration |
| `.dockerignore` | Docker ignore file |
| `Dockerfile-nodejs` | Node.js Dockerfile |
| `Dockerfile-wordpress` | WordPress Dockerfile |

Stop the running process with `CTRL/CMD+C`, rebuild, then start again:

<CodeTabs tabs={[{ label: "npm", code: "npm run build\nnpm run start" }, { label: "Docker", code: "docker compose build\ndocker compose up" }]} />

---

# Distribution Files

> Generate optimized distribution files for deploying your WordPressify theme.

Source: https://wordpressify.co/distribution-files

# Distribution Files

Generate production-ready files for your WordPress theme:

<CodeTabs tabs={[{ label: "npm", code: "npm run export" }, { label: "Docker", code: "docker compose run --rm nodejs npm run prod" }]} />

`npm run export` is a wrapper around the Docker command: the production build always runs inside the Node.js container, so both produce identical output. Use the Docker command directly if Node.js is not installed locally. If the Docker stack was not already running, `npm run export` automatically stops it again when the build finishes.

## What Gets Generated

The `dist/` folder contains your compiled theme:

- **CSS** - Minified with cssnano, autoprefixed.
- **JavaScript** - Transpiled with Babel, minified.
- **Theme files** - Block templates, `theme.json`, and PHP, copied as-is from `src/theme/`.
- **Assets** - Images and fonts from `src/assets/`.
- **Zip archive** - `dist/wordpressify.zip`, ready to upload to WordPress.

## Backups

To back up your local WordPress installation (core files, themes, plugins, and uploads), run:

```bash
npm run export:backup
```

This zips the full `build/` directory into `backups/<date>.zip`. The database is not included, as it lives in a Docker volume. Like `export`, it auto-stops the Docker stack afterwards if it was not already running.

## Deployment

You can upload `wordpressify.zip` manually through the WordPress admin (Appearance > Themes > Add New > Upload Theme), or set up automated deployments with GitHub Actions.

<Card title="Auto Deploy" icon="Rocket" href="/auto-deploy">
  Set up automatic deployment with GitHub Actions via FTP or SSH.
</Card>

---

# Auto Deploy

> Automatically deploy your WordPressify project using GitHub Actions with FTP or SSH.

Source: https://wordpressify.co/auto-deploy

# Auto Deploy

Deploy your WordPressify theme automatically with GitHub Actions whenever you push to `main`.

## Setup

<Steps>
  <Step title="Create a GitHub repository">
    Push your WordPressify project to a new GitHub repository.
  </Step>
  <Step title="Add secrets and variables">
    In your repository, go to **Settings > Secrets and variables > Actions**:

    - Under **Variables**, create `THEME_NAME` with your theme directory name (e.g., `my-theme`).
    - Under **Secrets**, add the credentials for your chosen deployment method (see below).
  </Step>
  <Step title="Create the workflow file">
    Create `.github/workflows/deploy.yml` in your repository and paste one of the configurations below.
  </Step>
</Steps>

## Deployment Methods

<Tabs>
  <TabContent title="FTP">
    Add these secrets to your repository: `FTP_SERVER`, `FTP_USERNAME`, `FTP_PASSWORD`.

    ```yaml
    name: Deploy WordPressify
    on:
      push:
        branches:
          - main
    env:
      THEME_NAME: ${{ vars.THEME_NAME }}

    jobs:
      deploy:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - name: Setup Node.js
            uses: actions/setup-node@v4
            with:
              node-version: "20"

          - name: Install dependencies
            run: |
              npm install
              npm run build

          - name: Build theme
            run: |
              npm run export

          - name: Set permissions
            run: |
              sudo chown -R $USER:$USER ./dist
              chmod -R 755 ./dist
              mkdir -p dist/themes/${{ env.THEME_NAME }}
              touch dist/themes/${{ env.THEME_NAME }}/.ftp-deploy-sync-state.json
              chmod 666 dist/themes/${{ env.THEME_NAME }}/.ftp-deploy-sync-state.json

          - name: Deploy to WordPress
            uses: SamKirkland/FTP-Deploy-Action@v4.3.4
            with:
              server: ${{ secrets.FTP_SERVER }}
              username: ${{ secrets.FTP_USERNAME }}
              password: ${{ secrets.FTP_PASSWORD }}
              local-dir: ./dist/themes/${{ env.THEME_NAME }}/
              server-dir: /public_html/wp-content/themes/${{ env.THEME_NAME }}/
              exclude: |
                **/.git*
                **/.git*/**
                **/node_modules/**
                **/src/**
                gulpfile.js
                package.json
                package-lock.json
    ```
  </TabContent>
  <TabContent title="SSH">
    Add these secrets to your repository: `SSH_HOST`, `SSH_USERNAME`, `SSH_KNOWN_HOSTS`, `SSH_PRIVATE_KEY`.

    ```yaml
    name: Deploy WordPressify
    on:
      push:
        branches:
          - main
    env:
      THEME_NAME: ${{ vars.THEME_NAME }}

    jobs:
      deploy:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4

          - name: Setup Node.js
            uses: actions/setup-node@v4
            with:
              node-version: "20"

          - name: Install dependencies
            run: |
              npm install
              npm run build

          - name: Build theme
            run: |
              npm run export

          - name: Set permissions
            run: |
              sudo chown -R $USER:$USER ./dist
              chmod -R 755 ./dist
              mkdir -p dist/themes/${{ env.THEME_NAME }}

          - name: Install SSH key
            uses: shimataro/ssh-key-action@v2
            with:
              key: ${{ secrets.SSH_PRIVATE_KEY }}
              known_hosts: ${{ secrets.SSH_KNOWN_HOSTS }}

          - name: Deploy to WordPress via SSH
            run: |
              rsync -avz --delete \
                -e "ssh -p 22" \
                --exclude '.git*' \
                --exclude '.git*/**' \
                --exclude 'node_modules/**' \
                --exclude 'src/**' \
                --exclude 'gulpfile.js' \
                --exclude 'package.json' \
                --exclude 'package-lock.json' \
                ./dist/themes/${{ env.THEME_NAME }}/ \
                ${{ secrets.SSH_USERNAME }}@${{ secrets.SSH_HOST }}:/var/www/html/wp-content/themes/${{ env.THEME_NAME }}/
    ```
  </TabContent>
</Tabs>

<Callout type="warning">
  Important notes:

  - Set `THEME_NAME` as a **repository variable** (not a secret). This is the name of your WordPress theme directory.
  - Do **not** commit your `.env` file to the repository if it contains sensitive values. Use GitHub secrets and variables instead.
  - Verify the `server-dir` (FTP) or rsync destination path matches your server's WordPress installation directory.
  - Keep at least one file in `src/plugins/` (even an empty `.gitkeep`). An empty directory will cause the build to fail.
</Callout>

## Triggering the Deployment

Once the workflow file is committed and pushed to `main`, every subsequent push to `main` will automatically build and deploy your theme.

<Callout type="info">
Secrets are encrypted and cannot be viewed once saved. You can update a secret at any time by creating a new one with the same name. Never commit credentials to your repository.
</Callout>

---

# Troubleshooting

> Common troubleshooting issues and solutions for WordPressify.

Source: https://wordpressify.co/troubleshooting

# Troubleshooting

<Accordion title="docker compose: command not found">
  **Issue:** Docker is not installed or not in your PATH.

  **Solution:** Install [Docker Desktop](/install-docker) and make sure it is running. Restart your terminal after installation.
</Accordion>

<Accordion title="Error: Docker is not running">
  **Issue:** Docker is installed but not running. WordPressify checks for Docker before executing any Docker command and shows this error if it is not available.

  **Solution:** Open Docker Desktop and wait for it to fully start before retrying the command.
</Accordion>

<Accordion title="Bind for 0.0.0.0:3010 failed: port is already allocated">
  **Issue:** The default proxy port (3010) is already in use by another process.

  **Solution:** Change the port in your `.env` file to a different value, e.g. `PROXY_PORT=3030`, and restart.
</Accordion>

<Accordion title="403 Forbidden or 502 Bad Gateway after starting">
  **Issue:** WordPress and the build tools are still initializing.

  **Solution:** Wait 10-20 seconds for the containers to finish setting up, then reload the page.
</Accordion>

<Accordion title="File changes are not detected (Windows)">
  **Issue:** The file watcher misses changes, so live reload does not trigger.

  **Solution:** The watcher uses polling by default, so this should work out of the box. If changes are still not detected, make sure Docker Desktop is using the WSL 2 backend. See the [Windows Installation](/windows-installation) page for details.
</Accordion>

<Accordion title="Node.js version mismatch errors">
  **Issue:** Your local Node.js version is incompatible with the project dependencies.

  **Solution:** Use Node.js 12.20 or later (any current LTS release works). If you do not want to install Node.js locally, run everything through Docker with `docker compose up`.
</Accordion>

---

# Windows Installation

> Windows-specific setup instructions for WordPressify.

Source: https://wordpressify.co/windows-installation

# Windows Installation

WordPressify works on Windows through Docker Desktop. No extra configuration is required.

## File Watching

The file watcher uses polling by default (it checks for changes every second), so live reload works on Windows out of the box.

## Recommended: WSL2 Backend

For the best performance on Windows, enable the WSL2 backend in Docker Desktop:

1. Open **Docker Desktop > Settings > General**.
2. Check **Use the WSL 2 based engine**.
3. Restart Docker Desktop.

WSL2 provides faster file system operations and better container performance compared to the Hyper-V backend.

<Card title="Install Docker" icon="Container" href="/install-docker">
  Download and install Docker Desktop for Windows.
</Card>

---

# Changelog

> Release history and version notes for WordPressify.

Source: https://wordpressify.co/changelog

# Changelog

<Update label="v0.6.3" description="Patch">
  - Add `update` subcommand for upgrading existing projects without overwriting theme source files.
  - Rebrand text domain from "creativeblocks" to "wordpressify" and modernize block theme metadata.
  - Improve accessibility with `prefers-reduced-motion` media queries and narrower CSS transitions.
  - Remove aggressive CSS global resets that conflict with WordPress block editor defaults.
  - Move `check-docker` script to project root.
  - Format gulpfile and fix project URL.
  - Update screenshot.
  - Add contributing guidelines.
</Update>

<Update label="v0.6.2" description="Patch">
  - Fix: store `.gitignore` as `gitignore_template` since npm never includes `.gitignore` in published packages.
</Update>

<Update label="v0.6.1" description="Patch">
  - Fix: add `.npmignore` so npm includes `.gitignore` and other dot files in the published package.
  - Simplify installer to copy files directly to final paths, removing all flat-copy-then-rename logic.
</Update>

<Update label="v0.6.0" description="Minor Release">
  - Update WordPress to 6.9, PHP to 8.5, and Xdebug to 3.5.1.
  - Update dependencies.
  - Replace GitHub downloads with local file copies in installer, removing `download` and `execa` dependencies.
  - Replace `chalk` and `prompts` with native ANSI codes and Node's `readline`, reducing installer dependencies from 100+ to 18 packages.
  - Export and export:backup scripts now auto-stop Docker containers when the stack was not already running, while preserving the correct exit code.
  - Resolve wordpress-chmod race condition by adding a healthcheck to the WordPress service.
  - Fix nginx 400 Bad Request error by increasing `large_client_header_buffers`.
  - Remove obsolete `version` key from docker-compose.yml and add default for `THEME_NAME`.
  - Remove missing `package-lock.json` from Dockerfile-nodejs COPY.
  - Add Docker availability check with colored error message before running Docker commands.
  - Add Doccupine to installer output and README with referral links.
  - Add CLAUDE.md for Claude Code guidance.
  - Reformat CHANGELOG to follow Conventional Commits.
</Update>

<Update label="v0.5.0" description="Major Release">
  - Updated the default theme, replacing PHP templates with HTML and modern block-based markup. Learn more about block-based themes [here](https://developer.wordpress.org/block-editor/explanations/architecture/key-concepts/).
  - Added code formatters: PHP CS Fixer for PHP code consistency and Prettier for HTML, JavaScript, and CSS.
  - Added `USE_POLLING` environment variable to enable file watcher polling as needed.
  - Enhanced build tasks so deleted files are automatically removed. Also resolved an issue where new images or fonts weren't being detected by the watch task.
  - Replaced `cssnano` with `gulp-clean-css` for improved CSS optimization.
  - Update PHP to 8.3.
  - Update default theme.
</Update>

<Update label="v0.4.0" description="Major Release">
  A new major release simplifies WordPressify even further. Removes Node.js as a global dependency, leaving Docker as the only main dependency. This allows WordPressify to run cross-platform without changing anything.

  - `npm run dev` replaced with `npm run start` or `docker compose up`
  - `npm run env:rebuild` replaced with `npm run rebuild` or `docker compose down -v`, then `docker compose build`
  - `npm run prod` replaced with `npm run export` or `docker compose run --rm nodejs npm run prod`
  - `npm run backup` replaced with `npm run export:backup` or `docker compose run --rm nodejs npm run backup`
  - `npm run lint:css` replaced with `npm run lintcss` or `docker compose run --rm nodejs npm run lint:css`
  - Update documentation and website.
  - Fix Windows build.
  - Fix Linux Docker permissions.
  - Fix Browsersync proxy server while using `wp-admin`.

  A special thank you to [@mountainash](https://github.com/mountainash) and [@vandr0iy](https://github.com/vandr0iy) for their contributions.

  [Release Notes](https://github.com/luangjokaj/wordpressify/discussions/126)
</Update>

<Update label="v0.3.0" description="Release">
  - Improve documentation and website.
  - Default header viewport meta tag.
</Update>

<Update label="v0.2.9" description="Release">
  - Development server using Docker with Xdebug support.
  - MariaDB database out of the box running in Docker.
  - `.editorconfig` for code style consistency.
  - GitHub Actions for simple testing.
  - **Breaking:** Docker is a required global dependency.

  A special thank you to [@ribaricplusplus](https://github.com/ribaricplusplus) for this contribution.
</Update>

<Update label="v0.2.8" description="Release">
  - Add ESLint with WordPress code standards rules.
</Update>

<Update label="v0.2.7" description="Release">
  - Fix readme documentation on install.
  - Fix cron jobs new formatting.
</Update>

<Update label="v0.2.6" description="Release">
  - Install files from versioned release instead of `master` branch.
</Update>

<Update label="v0.2.5" description="Release">
  - Install only required dependencies.
  - Update dependencies.
</Update>

<Update label="v0.2.4" description="Release">
  - Improve documentation.
</Update>

<Update label="v0.2.3" description="Release">
  - Improved installation speed for global dependencies.
  - **Breaking:** It is required to update WordPressify: `sudo npm install wordpressify -g`.
</Update>

<Update label="v0.2.2" description="Release">
  - Meta updates.
</Update>

<Update label="v0.2.1" description="Release">
  - Update dependencies.
</Update>

<Update label="v0.2.0" description="Release">
  - Fix typo.
</Update>

<Update label="v0.1.9" description="Release">
  - Fix dependencies.
</Update>

<Update label="v0.1.8" description="Release">
  - Run WordPressify globally from NPM.
</Update>

<Update label="v0.1.7" description="Release">
  - Remove WordPressify template from main repository.
  - Simple and unstyled boilerplate code.
</Update>

<Update label="v0.1.6" description="Release">
  - Upgrade to Gulp 4.
  - Rewrote all tasks into functions.
  - Updated file structure.
</Update>

<Update label="v0.1.5" description="Release">
  - Upgrade to Babel 7.
  - Removed deprecated `postcss-cssnext` in favor of `postcss-preset-env`.
</Update>

<Update label="v0.1.4" description="Release">
  - Added cleanup command to flush the default theme and have a fresh start.
</Update>

<Update label="v0.1.3" description="Release">
  - Added support for bitmap and SVG minification in the production build.
  - Added documentation for deployment process.
</Update>

<Update label="v0.1.2" description="Release">
  - Converted all variables from `var` to `const`.
  - Replaced long anonymous functions with ES6 arrow syntax.
  - Fix spelling errors.
</Update>

<Update label="v0.1.1" description="Release">
  - Added support for `src/plugins`.
</Update>

<Update label="v0.1.0" description="Release">
  - Code readability improvements.
  - Removed unused packages.
  - Build success and error messages.
  - Tasks cleanup.
</Update>

<Update label="v0.0.9" description="Release">
  - Update documentation.
</Update>

<Update label="v0.0.8" description="Release">
  - Name change.
</Update>

<Update label="v0.0.7" description="Release">
  - Fix placement of `DISABLE_WP_CRON`.
</Update>

<Update label="v0.0.6" description="Release">
  - Theme cleanup.
  - Consistent code styles.
</Update>

<Update label="v0.0.5" description="Release">
  - Activated `DISABLE_WP_CRON` to prevent Node freezing.
  - Back up your build files with all `wp-content` uploads.
</Update>

<Update label="v0.0.4" description="Release">
  - Fix whitelabel template.
  - Fix renamed classes.
  - Refactored CSS structure.
  - Meet WordPressify.
</Update>

<Update label="v0.0.3" description="Release">
  - Simplified build logic.
  - Install WordPress only once with `npm run install:wordpress`.
  - Cleaner distribution task.
</Update>

<Update label="v0.0.2" description="Release">
  - Bugfixes.
  - Watch and store new content in `wp-content/uploads`.
</Update>

<Update label="v0.0.1" description="Initial Release">
  - Initial release of WordPressify.
</Update>