This manual will setup a local dev environment for Magento 2.3+ and PWA Studio using Valet+ on a Mac.


  1. Use NVM to install Node 10.14.1+.
  2. Install Yarn.
  3. Install Composer.
  4. Install Valet+.
  5. Create a GitHub personal access token with “repo” permissions.
  6. Create Magento authentication keys.
  7. Add token and keys to your Composer authentication file: ~/.composer/auth.json

Create site in Valet

cd ~/work/valet
mkdir m2
cd m2
valet secure m2
valet db create m2

Install Magento

Decide which way you’ll install Magento:

  • Create a Composer package. Use this to build sites or integrate with Magento.
  • Clone the Git repository. Use this to contribute to Magento via pull requests.

Create a Composer package

Reference: Magento Dev Docs 2.3 — Install Magento using Composer

1. Choose Magento edition

# Install Magento Open Source (Community Edition)
composer create-project --repository= magento/project-community-edition .

# Install Magento Commerce (Enterprise Edition)
composer create-project --repository= magento/project-enterprise-edition .

2. Set file permissions

You can skip this entirely when using Valet. All permissions are fine.

find var generated vendor pub/static pub/media app/etc -type f -exec chmod g+w {} +
find var generated vendor pub/static pub/media app/etc -type d -exec chmod g+ws {} +

# For Ubuntu
chown -R :www-data .

chmod u+x bin/magento

3. Setup Magento

Visit https://m2.test/setup.

Clone the Git repository

Reference: Magento Dev Docs 2.3 — Clone the Magento repository

cd ~/work/valet
mkdir m2
cd m2
git clone .

# Switch to the active dev branch
git checkout 2.3-develop

composer install

Visit https://m2.test/setup.

Install sample data

Sample data is not compatible between the PHTML and PWA frontends.

For Luma (PHTML frontend)

Reference: Magento Dev Docs 2.3 — Install sample data after cloning

cd ~/work/repos

# Clone the sample data repo
git clone .

# Switch the sample data branch to match your Magento branch
git checkout 2.3-develop

# The "ce-source" param must have an absolute path to work
php -f ~/work/repos/magento2-sample-data/dev/tools/build-sample-data.php -- --ce-source="/Users/brendan/work/valet/m2"

# Upgrade the Magento database
php bin/magento setup:upgrade

For Venia (PWA frontend)

Reference: Magento PWA Docs — Install Venia sample data

You can skip this step and still demo the PWA. By default, PWA connects to a Magento Cloud backend instance that Magento maintains.

cd {projectRoot}

# Copy the file `` from the PWA Studio repo to this project root.
# See docs for reference.

# Allow execution
chmod +x

# Run script

# Upgrade the Magento database
php bin/magento setup:upgrade

Set Magento mode and refresh indexes

# Set developer mode (required for GraphQL validation in PWA)
php bin/magento deploy:mode:set developer

# Refresh indexes (required after installing sample data)
php bin/magento indexer:reindex

Install PWA Studio

Reference: Magento PWA Docs — Venia storefront setup

cd ~/work/repos
git clone .
yarn install
cp packages/venia-concept/.env.dist packages/venia-concept/.env

Connect PWA to your local Magento backend

You can skip this step until you need to connect to custom data locally.

In the PWA Studio repo you just cloned, edit the file: packages/venia-concept/.env. Change this line:


Serve the PWA

# Build PWA assets
yarn run build

# Start PWA server
yarn run watch:venia

See: Frameworks: Magento PWA Studio: Commands