Calvin Usage Guide for VTEX IO
Configuration Steps
1. Create a Workspace in VTEX IO
The first step is to create a workspace within Calvin for VTEX IO. Depending on what you want to build, you must choose between:
VTEX Store Theme workspace
VTEX Custom App workspace
VTEX Admin workspace
Make sure to select the option that matches your project type.
2. Connect a Project or Template
Once the workspace has been created, there are two possible options.
2.1 Use a Template
You can create a new project from a base template. To do so, click the corresponding button and select the appropriate VTEX template.
2.2 Connect to an Existing Repository
To connect Calvin to an existing repository:
Click the Settings button inside Calvin.
Select the option to connect to a repository and complete all required fields:
GitHub
Bitbucket
GitLab
Choose the branch you want to work with.
In the settings section, define the behavior when a chat is completed:
Automatically merge into the selected branch
Create a Pull Request to the selected branch
This configuration determines how Calvin will handle the code changes generated when a chat is completed.
3. Select the Correct Documentation
Inside Calvin’s settings, you must select the type of documentation you will be working with.
Available options:
VTEX IO
VTEX Admin
VTEX Custom App
It is important to select the option that corresponds to the type of workspace you previously selected.
4. Perform the First VTEX Link
After configuring the repository, it is necessary to run a VTEX link to your previously created VTEX IO workspace.
To do this:
Click the VTEX IO button in Calvin.
Complete the required fields.
Execute the link process.
Link Verification
It is recommended to verify that the process was completed successfully:
Click the Build button
Select View Logs
Check that there are no compilation errors
This initial link is essential because it allows Calvin to recompile the project and validate that generated changes do not contain errors.
5. Configure the Playwright MCP
For Calvin to interact with the browser and perform visual validations, you must configure the Playwright MCP.
Steps
Make sure Playwright MCP is installed.
Open a terminal and run:
Go to Calvin and enter the store where the workspace was created.
Click the Workspace Connectors button.
Select Add Custom MCP.
Complete the fields using the information displayed in the terminal.
Important:
Do not close the terminal where you executed pw-tunnel start.
If you close it, Calvin will lose access to the MCP.
Connection Verification
To confirm that the MCP is correctly connected:
Enter the workspace
Go to the connectors section
Verify that the MCP appears as connected
The first time (and occasionally afterward), you may need to log in to VTEX in the browser opened by Calvin.
6. Using Calvin in the Project
Once all previous steps are completed, Calvin is ready to be used in your VTEX IO project.
Suggestion for Pixel Perfect Implementation
To request a pixel perfect component implementation from Calvin, it is recommended to follow this workflow:
Attach the HTML file containing the component design.
Include a base prompt adapted to the component you want to develop.
Recommended Prompt
This prompt can be adapted and expanded according to the project’s needs by adding additional requirements or specific instructions.
Recommendations
Always check the logs after each VTEX link.
Keep the MCP active during the entire use of Calvin.
Visually review the generated implementations before completing a chat.
Use clear and specific prompts for better results.
When developing something complex, better and faster results are usually achieved by dividing the work into smaller, manageable parts. Instead of requesting everything in a single prompt, it is recommended to modularize what you want to achieve. For example, you can first ask Calvin to build only the base structure of the component, ensuring that all elements are correctly organized and positioned. Once that structure is validated, you can then request the pixel perfect design, adjusting styles, spacing, typography, and visual details.
Appendix: Playwright MCP Installation
For Calvin to control a local browser using Playwright, you must install and configure Playwright Tunnel MCP. Below are the installation steps.
Prerequisites
Node.js version 18 or higher
npm version 8 or higher
You can verify this with:
Step 1: Install the Package Globally
Run the following command:
Step 2: Install Dependencies
This command automatically installs:
ngrok (ngrok Tunnel)
Playwright browsers
Step 3: Start the Server with Tunnel
When executed, a public URL generated by Cloudflare will be displayed in the terminal. This information must be used to configure the Custom MCP inside Calvin.
It is important not to close the terminal while using Calvin, as the tunnel will be terminated.
Last updated