vtex

VTEX Toolbelt

CLI tool for developing VTEX apps.

Getting started

The VTEX Toolbelt can be installed via npm. If you don't have it installed, you can get it bundled with node:

• Linux
• Mac and Windows

Installing the VTEX Toolbelt

It's recommended that you install it globally (you may need sudo or administrative privileges):

npm install -g vtex

Warming up

Remember that your project needs to meet some requirements to work:

1. You need to have a VTEX ID credential in order to send the files to the sandbox or publish an app

2. Your app must have a proper meta.json, here's an example:

   {
       “name”: “app-name”,
       “version”: “0.2.0”,
       “vendor: : “vtex”
   }
   

3. You must properly set vtex_sandbox cookie

   The sandbox is used to test your apps that aren't published yet. You'll use a sandbox only if you're a VTEX apps developer.

   The sandbox it's a alternative version of an app that only you see under development.

   We need to tell to Storefront that we'll use a new sandbox. We do that by defining a special cookie on the browser, with the name vtex_sandbox and the value vtex/mysandbox=myapp.

   In order to do that, we can use a browser extension that eases the manipulation of cookies. If you use Chrome, we recommend the Cookie Inspector. To create a new cookie open the Developer Tools and click on the Cookies tab. Then you can click with the right mouse button and choose the "Add New Cookie".

   Edit this cookie with the following properties:

   Name	Value
   vtex_sandbox	vtex/mysandbox=myapp

Developing an app

If you need help with the structure of your project or you just don't want to spend the time with this tinkering, you can use our generator!

On the root of your project, run the vtex watch <sandbox-name>.

That should do it! The VTEX Toolbelt watcher will be monitoring your files and send them to the VTEX Gallery as soon as you edit them.

For more information on the commands, options and other configs, you can seek more information below!

---

Auth

You can use vtex login to login with yout VTEX ID credentials or vtex logout if you're already logged in and want to change credentials.

Note that watch and publish implicitly checks if you're logged, and if you're not, it asks your credentials before proceeding.

Watch

To develop an app locally, open the directory where your VTEX app is and then type:

vtex watch <sandbox-name>

You are free to set any name you want in the sandbox-name parameter, as long as it contains only letters, numbers, underscores and hyphens.

VTEX Toolbelt will upload all your app files to the sandbox specified and will be watching for any changes you make to them.

There's other forms of use too, if you use the options:

Option	Alias
vtex watch --webpack <sandbox-name>	vtex watch -w <sandbox-name>
vtex watch --server <sandbox-name>	vtex watch -s <sandbox-name>

Webpack

You can run the VTEX Toolbelt watcher in parallel with the Webpack watcher if you use the --webpack option under the watch command.

Make sure that you have a well configured and working webpack.config.js on the root of your project.

vtex watch --webpack <sandbox-name>

Dev Server

You can also run the VTEX Toolbelt watcher in parallel with the Dev Server watcher if you use the --server option under the watch command.

As Dev Server uses Webpack, you also need a webpack.config.js file on the root of yout project.

vtex watch --server <sandbox-name>

You need to call it this way if you want to enable Hot Module Replacement, see below for more information on how to configure your project for this.

Livereload

Add to your layout the following script:

<script src="http://localhost:35729/livereload.js?snipver=1"></script>

Hot Module Replacement

First things first, you need to use babel. Then, there's a few packages you need to install:

• babel-plugin-react-transform
• react-transform-hmr
• react-transform-catch-errors (actually, this one is opcional)

You can install them using npm i <package-name> --save-dev on the root folder of your project (the --save-dev adds that package to the devDependencies of your package.json).

After that, create a .babelrc file on the root folder of your project with the following:

{
  "stage": 0,
  "env": {
    "development": {
      "plugins": ["react-transform"],
      "extra": {
        "react-transform": {
          "transforms": [{
            "transform": "react-transform-hmr",
            "imports": ["react"],
            "locals": ["module"]
          }, {
            "transform": "react-transform-catch-errors",
            "imports": ["react", "redbox-react"]
          }]
        }
      }
    }
  }
}

Presto! Everything is configured and ready to use. Remember to use the following URL while running vtex watch -s <sandbox-name>:

<store-name>.local.myvtex.com:3000

VTEX Ignore

The VTEX Ignore it's a file that you can put on the root of your project, naming it .vtexignore.

This files tells watch which files he shouldn't send to the server. If no .vtexignore is found, it fallbacks to the .gitignore file.

Publish

To publish your VTEX app to VTEX Gallery, just type vtex publish. The app will be published under the vendor name.

Troubleshooting

Cannot resolve module 'react/lib/ReactMount'

If an error of this sort occurs:

ERROR in ./src/components/MyComponent.jsx
Module not found: Error: Cannot resolve module 'react/lib/ReactMount' in /home/username/projects/mycomponent/src/components
 @ ./src/components/MyComponent.jsx 1:350-381

Add ReactMount to your webpack.config externals:

externals: {
  'react/lib/ReactMount': 'ReactMount',
  'react': 'React'
},

License

MIT

Changelog

[0.10.0] - 2015-10-27

Hello, fellow developers!

I'm glad to announce that THE COOKIE IS DEAD!!11!!

Ok... maybe not that much. Let me explain:

The cookies for the sandbox and workspace pretty much still exists, BUT, we've created a good and ol' barrel of abstraction on top of it so you don't have to worry anymore.

Now we have a convention for setting those cookies. We will create a workspace with the name sb_<your-vtex-developer-email> and on that workspace you'll have a sandbox with the name <your-vtex-developer-email>. Because of that, you don't need to type the sandbox as an argument of watch anymore!

You will access those by simply putting a querystring on the link you use for development, for example: storename.beta.myvtex.com/?workspace=[e-mail].

All we ask in return is that when you log in you inform us the account you wish to be logged (yeah, only one account at a time).

I know you're excited, yeah, gimme a hug homie <3

TL;DR: You don't need to type the sandbox name on watch or set the cookies anymore.

First big important note: If you have any credentials cached, please logout and login again.

Second big important note: Delete the previous vtex_workspace and vtex_sandbox cookies that you have setted before.

• #58
• #48 (closed due to deprecation)