# Start Project

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

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

> For the complete documentation index, see [llms.txt](https://wordpressify.co/llms.txt).

# 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.