Skip to content
Admin Platform

Getting Started

This is the entry point for the Raccoon documentation. Here you will find all the information you need to start building your Next.js applications for the VTEX Admin.

What is Raccoon?

Raccoon is a set of tools and libraries that help you build and deploy Next.js applications for the VTEX Admin. It provides a set of functions to connect your Next.js app with VTEX IO, and it also provides a set of components and hooks to help you build your app.

It is composed of two main packages:

  • @vtex/raccoon-next: The core package that provides the functions to connect your Next.js app with VTEX IO.
  • @vtex/raccoon-io: An utility package that provides you with the means to communicate with your Next.js app from a VTEX IO app.

And a component from the Admin Shell:

Together, these tools enable the development of Admin apps powered by Next.js.

Creating a Raccoon application through DK Portal

This is the simplest way to create a Raccoon application. If you can just click on the link below and follow its guided steps. Alternatively, you can use the create-raccoon-app CLI below (which is used under the hood by DK Portal), or you can set up your application manually.

Use DK Portal to scaffold your new Raccoon application

Creating a Raccoon application with the create-raccoon-app (CRA) CLI

  1. Initialize the app using CRA

    Terminal window
    pnpm dlx @vtex/create-raccoon-app@latest

    Your fresh Raccoon app will be created in the admin-{app-name} folder, and have the project structure described here.

  2. Start developing

    Jump into the folder created by the CLI. Install the dependencies using the package manager of your choice and start the development server.

    Terminal window
    pnpm i && pnpm dev

Manual Setup

  1. Install @vtex/raccoon-next package

    Terminal window
    pnpm i @vtex/raccoon-next

  2. VTEX IO Admin integration setup

    Although you are building a Next.js app, you still need to declare the admin and messages builder for it, as in this manifest.json example:

    {
      "name": "raccoon-nextjs-example",
      "vendor": "vtex",
      "version": "0.0.1",
      "title": "Raccoon Next.js SDK",
      "description": "",
      "mustUpdateAt": "2022-08-28",
      "scripts": {
        "postreleasy": "vtex publish"
      },
      "dependencies": {},
      "builders": {
        "admin": "0.x",
        "messages": "1.x"
      },
      "$schema": "https://raw.githubusercontent.com/vtex/node-vtex-api/master/gen/manifest.schema"
    }

    For VTEX IO to correctly map your app route and host, you need to declare them on the /admin/navigation.json (refer to the admin-shell docs to understand these properties) file, following this example:

    {
      "section": "{section}",
      "titleId": "admin-example.navigation.label-group",
      "adminVersion": 4,
      "subSection": "some-subsection",
      "subSectionItems": [
        {
          "labelId": "admin-example.navigation.label-main",
          "path": "/admin/example",
          "raccoon": {
            "prodUrl": "https://my-app.admin.vtex.com",
            "devUrl": "http://loalhost:3000",
            "routes": [
              "/admin/example/all-internal-pages",
              "/admin/example/:dynamic-parameter"
            ]
          }
        }
      ]
    }

    You will also need to keep declaring the message IDs of your app under the messages folder.

  3. Next.js App Setup

    Use the connect and bootstrap functions to establish a connection between the Next.js application and the VTEX IO Admin.

    import type { AppProps } from 'next/app'
    import { connect, bootstrap } from '@vtex/raccoon-next'
    

    connect()
    

    function App({ Component, pageProps }: AppProps) {
      return <Component {...pageProps} />
    }
    

    export default bootstrap(App)

  4. Develop the application

    Once you finished configuring your app, you can start developing it by running the development server.

    Terminal window
    pnpm dev