Getting started

Run your storefront locally

Run your storefront on your computer with your project’s page content and Commerce catalog, so you can preview code changes before sharing them.

Use your team’s existing storefront project, based on the Adobe Commerce boilerplate, without creating another repository or configuring a new backend.

Get the project details

Gather these details from the maintainer of your storefront so you can check the same content and catalog locally:

What you need	What to confirm
Repository URL and access	You can open the repository on GitHub and clone it.
Content preview URL	You can open the team’s working preview, such as `https://main--your-storefront--your-org.aem.page`.
A content page path	The page displays text and layout you can recognize in the local preview.
A product page path	The page displays a known product from the expected catalog.
Storefront configuration	The project has the approved connection settings for your development environment.
Development access	You have any permissions or network access needed to load content and call Commerce services.

Use the exact preview URL your team provides, not the example above. In that URL, the origin is the address before the page path. For example, https://main--your-storefront--your-org.aem.page is the origin, and /about is a page path.

Keep both parts so you can use the origin to start the server and the page paths to check the local preview.

Check the content and product pages on that remote preview before setting up locally. If either fails, ask the project owner to resolve it first, since a local server cannot repair missing content or an unavailable catalog.

If a storefront project does not exist yet, Create a storefront covers repository, content, and Commerce connection setup. Project prerequisites and Backend options explain the required access and services. If someone else manages project setup, share the checklist above with them.

Prepare your computer

Install Git, a code editor, and the Node.js version your project uses. For a new setup based on the current storefront template, use Node.js 24 LTS (long-term support). Installing Node.js also gives you npm, the package manager used in the commands below.

In your terminal, check the tools:

1
git --version
2
node --version
3
npm --version

Each command prints a version. If a command is not found, finish installing that tool and open a new terminal before continuing.

You will also use the Adobe Experience Manager command-line interface, called the AEM CLI, for the local preview. Because it comes with the project’s dependencies, you do not need to install it globally.

Understand the local preview

Your local server serves code from the repository on your computer and fetches page content from your team’s preview site. Shopping data still comes from remote Commerce services, so the preview is not an offline installation. Starting it does not create a Commerce backend on your machine.

For those connections to work, you need a reachable content source and a working Commerce environment. Use your team’s approved development data and configuration, and keep passwords and private API credentials out of storefront code.

Because shopping requests still reach those remote services, signing in, changing a cart, or placing an order can affect shared data. Confirm that you are using an approved development environment before testing those actions. The checks below only require viewing pages.

The storefront reads its connection settings from the /config.json URL on the local server. Even if no configuration file exists in your repository, the local server can retrieve it from the remote preview. Before creating or replacing a local file, ask your team how configuration is supplied and check Storefront configuration for the supported approaches.

Start the storefront

The commands below run from the storefront repository, not from this documentation repository.

Clone your team’s repository.

Cloning creates a local copy of the project. In a terminal, replace the example URL with the repository URL your team provided:
Terminal window
```
1
git clone https://github.com/your-org/your-storefront.git
```
If you already have a local clone, use it instead of cloning again.
Change to the project directory.
Terminal window
```
1
cd your-storefront
```
Replace your-storefront with the directory that Git created. This directory contains the project’s package.json file.
Install the project dependencies.
Terminal window
```
1
npm install
```
Wait for installation to finish successfully. The installation includes the shopping packages already declared by the project, so you do not need to install cart or checkout separately.
Prepare the installed drop-in assets.
Terminal window
```
1
# The current template disables automatic install scripts.
2
npm run install:dropins
```
The current template sets ignore-scripts=true in .npmrc, which prevents npm install from running this preparation automatically. Keep this security setting enabled when running the explicit preparation command.

This command applies the project’s GraphQL query changes and copies the installed drop-in files into scripts/__dropins__/, where the browser loads them. GraphQL is the language the drop-ins use to request shopping data. Wait for the command to finish without errors.

If your project has different setup scripts, follow its documented commands with the project owner rather than adding a missing script yourself.
Start the development server with your team’s content preview URL.
Terminal window
```
1
# Replace the example URL with your team's content preview origin.
2
npm start -- --url https://main--your-storefront--your-org.aem.page --no-stop-other
```
The standard storefront start script runs aem up. The -- passes the following options through npm to that command. Use the origin only, without the content or product page path.

The --no-stop-other option prevents the CLI from stopping another AEM development server. If the requested port is busy, use a different port as described below.
Open the local address printed by the server.

The default is http://localhost:3000. Keep the terminal running while you develop.

The URL option selects the page content source. It does not configure or replace your Commerce connection.

Check the result

Check page content and Commerce data separately so you can tell which connection needs attention if a page fails:

Open your known content page at the local address.

For example, a content page at /about becomes http://localhost:3000/about. Confirm that the expected text and layout appear.
Open your known product page at the same local address.

Confirm that the product name and other catalog details match the environment your team provided. A visible header confirms that some page content loaded, but it does not confirm the Commerce connection.
Open the storefront directory in your code editor.

Confirm you can find blocks/, styles/styles.css, and package.json.

Once page content and Commerce data both load locally, the preview is ready for code and styling changes. This process does not verify every shopping feature. Starting the server has not published any code changes.

Troubleshoot local setup

What you see	What to check next
Clone fails or the repository is not found	Confirm the repository URL, your GitHub access, and the authentication method your team uses.
Dependency installation fails	Read the first error in the terminal. Confirm your project’s Node.js version and any required package access before retrying.
Drop-in preparation fails	Read the first error from `npm run install:dropins`. Confirm that dependency installation completed and that the command matches your project’s setup instructions. Do not disable the lifecycle-script security setting to work around the error.
The server cannot use port `3000`	Choose a different port, for example, `npm start -- --url https://main--your-storefront--your-org.aem.page --no-stop-other --port 3001`. Open the address it prints. Stop an existing server only if you own it.
The local page is missing or shows the wrong content	Open the same path on the team’s preview site. Confirm the content preview URL passed to the server and ask the content owner to check the page if it is also missing remotely.
Content loads but product data does not	Open the browser’s developer tools and reload the page. In the Network panel, check for failed `/config.json`, JavaScript, or Commerce requests. A missing module can indicate incomplete drop-in preparation. Confirm the response and expected environment with the project owner before changing settings.
Configuration changes do not appear	The storefront caches configuration in the browser session. Follow Testing configuration changes rather than repeatedly replacing the file.

If the team preview also fails, resolve that shared content or Commerce issue before treating it as a local code problem.

Continue development

To stop the local server, press Ctrl+C in the terminal where it is running. To resume later, run the same start command from a terminal in the project directory. You only need to reinstall dependencies when the project requires it, not before every preview.

For a new or changed Commerce connection, complete Verify your storefront setup for the required shopping features. A working local preview alone does not confirm cart, checkout, or account integration.

On an existing project with an unchanged connection, continue with Make your first change. There is no need to repeat every shopping check for the styling exercise.