Creating a B2B store

The B2B Buyer Portal store is a FastStore Discovery storefront with the Buyer Portal plugin and a Checkout customization, published as the vtex-sites/b2b.store template. fsp can start a monorepo from it or add it to a monorepo you already maintain. Both paths key the template to your account and leave you with the same layout fsp dev and fsp build expect from any other store.

Note

fsp downloads the template as an archive of its default branch, so you need network access to GitHub while running the command. No git binary is required.

Starting a new monorepo

1. Run init with the template

   npx @vtex/fsp-cli init --template b2b.store

   You will be asked for the account name and for the directory to create, which defaults to the account name.
2. Install the dependencies and start developing

   cd <directory>
   yarn install
   npx fsp dev <account>

The directory holds the template as published — its root package.json, turbo.json and README included — with every {ACCOUNT_NAME} replaced by your account. init changes only what the monorepo contract needs: packages/checkout declares @vtex/checkout (moved there from the root devDependencies), and the workspace and isolation settings cover both modules. The template’s own resolutions and postinstall are kept; its README explains why yarn build needs them. The template is a Yarn Classic monorepo and init keeps it that way, packageManager included.

Adding a B2B store to an existing monorepo

1. From the monorepo root, run create with the template

   npx fsp create <account> --template b2b.store

   Or answer B2B Buyer Portal when the fsp create wizard asks for the store type.
2. Keep the modules you want — discovery and checkout are both selected by default — and accept or change the path offered for each.
3. Let the repair step finish. It declares each module’s CLI, adds the modules to the workspace globs and runs the install, whether or not anything needed repairing, so the copied modules’ dependencies are in place.
4. On Yarn Classic, read the warning the command printed and add the template’s postinstall to your root package.json scripts, then run yarn install again. The warning shows the script already pointing at the paths you chose. If you added only checkout, the warning names the script but does not show it: it acts on the Discovery module, which you did not add. See below for why.

faststore.json gains a stores.<account> entry with the paths you chose and ports allocated after the modules the account already has. If the template’s own layout (packages/discovery, packages/checkout) is taken by another store, the default path moves to ./packages/<account>/<module>. Each module’s package.json is renamed <account>-<module> (acme-discovery, acme-checkout), so two B2B stores in the same monorepo do not collide on workspace names.

To add a single module of the template, name it:

npx fsp create <account> checkout ./packages/<account>/checkout --template b2b.store

What is not carried over

The monorepo root is shared with every other store in it, so create does not copy the template’s root files. Two things from that root matter to the B2B modules:

• workspaces.nohoist — on Yarn Classic, create merges the template’s globs (@vtex/faststore-plugin-buyer-portal, @vtex/checkout-ui-core) into your root manifest. Other package managers already keep each module’s dependencies apart with the setting fsp init wrote.
• resolutions and postinstall — printed in a warning, not applied. On Yarn Classic the nohoist globs above make Yarn nest a second copy of react and react-dom under the Discovery module, next to the root’s, and the build crashes with Cannot read properties of null (reading 'useEffect'); the template’s postinstall removes that copy after every install. That is why step 4 asks you to carry it over. On pnpm there is a single react in the store and the modules only link to it — the script is not needed, and would delete the module’s only react if run. npm is untested. Read the template README for the rest of the reasoning.

Troubleshooting

Message	Cause	What to do
Could not download template b2b.store (vtex-sites/b2b.store@main): …	No route to GitHub, or the repository is not public	Check your connection or proxy; the template must be reachable at its archive URL
Template b2b.store does not match the monorepo template contract: …	The template’s faststore.json changed shape, a module lost its package.json, or the template gained a symbolic link	The message names the rule; report it to the template maintainers
No package.json here. fsp create --template b2b.store adds modules to an existing monorepo…	The current directory is not a monorepo root	cd to the root, or run fsp init --template b2b.store to start a monorepo from the template
<module> has already been initialized for <account>.	The account already has that module in faststore.json	Pick the other module only, or another account
b2b.store ships discovery, checkout; it has no <module> module.	The module argument is not one the template provides	Use one of the listed modules
<path> already exists and is not empty	The chosen directory has files	Choose another path or clear the directory