Welcome to the comprehensive documentation for MagePWA CLI. This guide covers everything you need to know to get started and make the most of the tool.
npm install -g magepwa-cli
cd your-magento-pwa-project
magepwa init
magepwa init # Add scaffolds to existing Magento PWA project
magepwa regions # Copy regions manager scaffold files
magepwa tax-invoice # Copy tax invoice scaffold files
magepwa freegift # Copy free gift scaffold files (requires Amasty extension)
magepwa doctor # Check environment prerequisites
magepwa --help # Show help information
After running magepwa init in your existing Magento PWA project, it will add:
src/
├── targets/ # Custom build targets and interceptors
│ ├── local-intercept.js
│ ├── VeniaResolverPlugin.js
│ └── extend-configured-route.js
├── contexts/ # Store context configuration
│ └── store.js
├── overrides/ # Component override directories
│ ├── venia-ui/ # Venia UI overrides
│ ├── peregrine/ # Peregrine overrides
│ └── pagebuilder/ # Page Builder overrides
└── ...
# Root level configuration files
├── serve.js # Development server configuration
├── theme.js # Theme configuration with Tailwind
├── tailwind.config.js # Tailwind CSS configuration
├── webpack.config.js # Enhanced webpack configuration
└── upward.yml # Upward configuration
The CLI supports overriding components from three main modules:
Create files with the exact same path as the original:
src/overrides/venia-ui/components/AccountChip/accountChip.js
Override talons and utilities:
src/overrides/peregrine/talons/AccountMenu/useAccountMenu.js
Customize Page Builder elements:
src/overrides/pagebuilder/ContentTypes/ButtonItem/buttonItem.js
Access store configuration anywhere in your app:
import { useStoreContext } from '@contexts/store';
const MyComponent = () => {
const { product_url_suffix, store_code } = useStoreContext();
// Use store configuration
};
The CLI sets up enhanced build configuration:
# Copy regions scaffold to current directory's src folder (default)
magepwa regions
# Copy to a specific project directory
magepwa regions --dir /path/to/project
# Copy to a custom destination folder
magepwa regions --dir /path/to/project --dest components
# Copy to current directory with custom destination
magepwa regions --dest src/components
-d, --dir <path> - Target directory to copy files to (default: “.”)--dest <path> - Destination subdirectory within target directory (default: “src”)// Import the components in your React components
import District from '@components/Address/District';
import SubDistrict from '@components/Address/SubDistrict';
import { useDistrict } from '@talons/Address/District/useDistrict';
import { useSubDistrict } from '@talons/Address/SubDistrict/useSubDistrict';
// Use in your component
const AddressForm = () => {
const { districts, loading } = useDistrict();
const { subDistricts, loading: subLoading } = useSubDistrict(selectedDistrict);
return (
<div>
<District
districts={districts}
loading={loading}
onSelect={setSelectedDistrict}
/>
<SubDistrict
subDistricts={subDistricts}
loading={subLoading}
onSelect={setSelectedSubDistrict}
/>
</div>
);
};
# Copy tax invoice scaffold to current directory's src folder (default)
magepwa tax-invoice
# Copy to a specific project directory
magepwa tax-invoice --dir /path/to/project
# Copy to a custom destination folder
magepwa tax-invoice --dir /path/to/project --dest components
# Copy to current directory with custom destination
magepwa tax-invoice --dest src/components
-d, --dir <path> - Target directory to copy files to (default: “.”)--dest <path> - Destination subdirectory within target directory (default: “src”)// Import the components in your React components
import TaxInvoice from '@components/CheckoutPage/TaxInvoice';
import { useTaxInvoice } from '@talons/CheckoutPage/TaxInvoice/useTaxInvoice';
import { validateTaxInvoiceForm } from '@utils/validateForm';
// Use in your component
const CheckoutPage = () => {
const { taxInvoiceData, loading, submitTaxInvoice } = useTaxInvoice();
return (
<div>
<TaxInvoice
data={taxInvoiceData}
loading={loading}
onSubmit={submitTaxInvoice}
validate={validateTaxInvoiceForm}
/>
</div>
);
};
⚠️ Important Prerequisites: The Free Gift components require the Amasty Free Gift Magento 2 extension to be installed on your Magento backend, along with the corresponding GraphQL module. These components will not work without the proper backend extension.
# Copy free gift scaffold to current directory's src folder (default)
magepwa freegift
# Copy to a specific project directory
magepwa freegift --dir /path/to/project
# Copy to a custom destination folder
magepwa freegift --dir /path/to/project --dest components
# Copy to current directory with custom destination
magepwa freegift --dest src/components
-d, --dir <path> - Target directory to copy files to (default: “.”)--dest <path> - Destination subdirectory within target directory (default: “src”)Before using the Free Gift components, ensure you have:
// Import the components in your React components
import FreeGift from '@components/FreeGift';
import { useFreeGift } from '@talons/FreeGift/useFreeGift';
import { useFreeGiftSelection } from '@talons/FreeGift/useFreeGiftSelection';
import { useGiftPromotions } from '@talons/FreeGift/useGiftPromotions';
// Use in your component
const CartPage = () => {
const { freeGifts, loading } = useFreeGift();
const { selectedGifts, selectGift } = useFreeGiftSelection();
const { promotions, loading: promotionsLoading } = useGiftPromotions();
return (
<div>
<FreeGift
gifts={freeGifts}
loading={loading}
onSelect={selectGift}
selectedGifts={selectedGifts}
promotions={promotions}
promotionsLoading={promotionsLoading}
/>
</div>
);
};
The Free Gift scaffold includes:
Use these aliases for cleaner imports:
@ - src directory@components - src/components@utils - src/utils@hooks - src/hooks@talons - src/talons@overrides - src/overrides@i18n - src/i18nsudo if needed for global installationUse the doctor command to verify your environment:
magepwa doctor
This will check: