Modules
What a module installs, how it gets onto your page, how it connects to your API and how to remove it.
What a module is
A module is a feature that runs inside src/features/<name>: components, API functions, hooks, schemas and tests, in the same structure as the template and the ViraStack AI rules.
Modules run on a dummy API or dummy data. Connecting your real API and adapting the response model is up to you.
Ready modules
| Module | What it does |
|---|---|
users | A user table with search, pagination, and actions to add, edit and delete users. |
auth | Sign-in and sign-up pages: sign in with a username and password, watch the password's strength as you type and create an account; error and success states come ready. |
products | A product list with search, category, sorting and pagination in the URL, and a page for each product with its images, details and reviews. |
cart | A cart page: pick the items to check out, change quantities, remove items and apply a coupon code; the summary recalculates with every change. |
checkout-address | The chosen address shows on the page; listing, adding and editing happen in a popup. Shipping and billing can differ. |
checkout-card | The chosen card shows on the page; saved cards are listed in a popup, where you can add a new one. The card number and CVV never reach the network, and you connect your payment provider in one place. |
Each module's live preview, its code for all four templates and the prompt for your agent are in the module catalog.
Requirements
- A project created with ViraStack Start 2.0 or newer. The command does not run in a project not created with Start; in an older Start project it prints the version it needs and installs nothing.
- Any of the four templates: Next.js and TanStack Start, with or without i18n. The CLI reads the template from the project and installs the matching files.
- An internet connection. Modules download from the ViraStack registry.
Add a module
Run it in the project root:
$ pnpm dlx virastack@latest add usersThe command:
- Copies the module's files into
src/features/<name>. - Installs missing packages and
components/uicomponents with the project's package manager. - Merges its text into
src/messagesin i18n templates. For a language the module has no translation for, it adds the English text and tells you. - Brings the module's tests; the project's
testscript runs them too. - Prints where the module's pages are; for a module without pages, the main component's import line and the module page's link.
A module with pages brings them: products adds its list at /products and a page per product under it, cart adds the cart at /cart, and auth adds sign-in at /login and sign-up at /register. If your project already has a route at one of those addresses, nothing changes and the CLI lists it; --no-pages installs the feature alone. Other modules create no page: you decide where they show up.
In a Next.js project created before Start 2.2, delete src/app/loading.tsx. While it stays, a missing product answers 200 instead of 404 and the page's content is hidden without JavaScript. New projects do not have this file.
If the project already has a file or text with the same name, nothing changes and the CLI lists the conflicts. If the module is already installed, the command does nothing.
Add it to a page
A module without pages, or one installed with --no-pages, goes on a page of yours, in one of two ways. Either way the module's code stays as it is; only a new page gets written.
With an AI coding tool
The Prompt button on the module's page copies one prompt that works for both frameworks. Your agent installs the module, opens a page the way your framework does it, renders the main component and runs the typecheck, test and lint:ci scripts.
By hand
Open a new page in your framework's routing, then import and render the module's main component. Its name and path are in the import line the CLI prints after installing and in the Code tab of the module's page.
- Next.js: a
page.tsxundersrc/app; undersrc/app/[locale]in i18n templates. - TanStack Start: a route file under
src/routes; undersrc/routes/{-$lang}in i18n templates.
Modules that keep search and pagination in the URL (such as users) need two more steps: on Next.js, wrap the component in Suspense; on TanStack Start, add the module's search schema to the route definition. The prompt on the module's page spells these out.
Example: a checkout page
checkout-address and checkout-card are separate modules. Install both with add, then render CheckoutAddress and CheckoutCard on the same page.
Features cannot import each other, and shared folders cannot import features, so the page ties the two together. The useCheckoutAddress hook returns the chosen address and useCheckoutCard the chosen card.
The card side carries a token, the bank, the brand, the last four digits, the expiry and the name; the card number and CVV never leave the browser. Call the hooks in a client component next to the page on Next.js, and in the route component on TanStack Start.
Connect your API
Set your API's address in .env.local: NEXT_PUBLIC_API_URL on Next.js or VITE_API_URL on TanStack Start.
If your responses differ, adapt the module's schemas and api folders. Each module's page lists the files to change under How do you use it?.
Remove a module
$ pnpm dlx virastack@latest remove usersDeletes the module's files, the folders it leaves empty and its text. Packages stay, because other code may use them.
If you changed any of those files, it lists them and asks first. In a script, pass --yes to delete them too; without it nothing changes.
The module's own pages go with it. A page you changed, or your own page after --no-pages, is listed before anything is deleted and goes only if you say yes; with --yes or in a script it stays, and the CLI warns that it may still import the module. A page you wrote yourself elsewhere stays: remove its import yourself.