Template developers: Installation

Set up your local environment for building composable, data-aware templates in the Web Builder.

Prerequisites

• Node.js 18+ and a package manager (yarn, npm, or pnpm).
• A local erxes instance running (Option A). Follow the official guide: https://erxes.io/docs/local-setup
• Git access to the Web Builder monorepo and template repos (ask your senior dev to grant access).

---

Installation options

Choose one setup path depending on how you plan to connect erxes.

---

Option A: Based on local erxes (current flow)

1. Clone the Web Builder monorepo

git clone [email protected]:pages-web/web-builder.git
cd web-builder

If the team standardizes on a package manager, stick to it to avoid lockfile churn.

---

2. Install dependencies (Web Builder root)

yarn install
# or: npm install
# or: pnpm install

---

3. Clone a template boilerplate

In web-builder/apps/templates, clone the template you need (you will only update UI):

cd apps/templates
# choose one:
git clone [email protected]:erxes-web-templates/ecommerce-boilerplate.git
# or
git clone [email protected]:erxes-web-templates/tour-boilerplate.git

---

4. Configure environment

1. Copy any example env file if present:

cp .env.example .env.local

2. Add CMS/API variables needed for data-aware sections (e.g., CMS_BASE_URL, API_TOKEN). Keep secrets out of version control.

If your template uses static data during development, you can skip API tokens and rely on mocked JSON fixtures.

---

5. Run the Web Builder locally

Start the dev server:

yarn dev

Then open http://localhost:3000. Confirm that:

• Global layout renders (header/footer/theme).
• Sections load with either live CMS data or mocked data.
• Hot reload works when you edit a section or component.

---

6. Verify linting and build

yarn lint   # catches accessibility, typing, and styling issues early
yarn build  # ensures templates compile before pushing

Run these before opening a PR to keep the template stable for designers and content editors.

---

Option B: Based on SaaS erxes

1. Clone a SaaS-dependent template

git clone -b saas-dependent [email protected]:erxes-web-templates/ecommerce-boilerplate.git
cd ecommerce-boilerplate

2. Install a CORS browser extension

Ensure a CORS extension is installed and enabled in your browser for local development.

3. Set SaaS environment variables

Configure the environment values in next.config.ts. Use the current SaaS values for your project:

export default {
  env: {
    ERXES_API_URL: "https://sales.app.erxes.io/gateway/graphql",
    ERXES_URL: "https://sales.app.erxes.io/gateway",
    ERXES_FILE_URL: "https://sales.app.erxes.io/gateway/read-file?key=",
    ERXES_CP_ID: "nwYOCDEOph3oAqo73dHq0",
    ERXES_APP_TOKEN: "<redacted>",
    NEXT_PUBLIC_POS_TOKEN: "<redacted>"
  },
  images: {
    unoptimized: true,
    remotePatterns: [
      {
        protocol: "https",
        hostname: "sales.app.erxes.io",
      },
    ]
  },
};

ERXES_APP_TOKEN, NEXT_PUBLIC_POS_TOKEN, and ERXES_CP_ID change per project.

4. Run the template locally

yarn dev

---

Next steps

Move on to Template Structure to see how pages, sections, and shared components are organized for composability and data-awareness.

Edit this page