Pular para o conteúdo principal

Getting Started

danger

This SDK is a Work In Progress! All features are subject to change.

Scaffolding Your First Nube App​

These commands download and run the create-nube-app CLI, which will guide you through the process of setting up your project.

info

Compatibility Note

Nube SDK requires Node.js version 16+. Please upgrade if your package manager warns about it.

npm create nube-app@latest

Manual Setup (Advanced)​

We strongly recommend using the create-nube-app CLI, which provides templates, pre-configured build scripts, and development tooling aligned with the NubeSDK ecosystem.

However, if you're unable to use the CLI for any reason, you can set up your project manually. To do this, make sure to install the necessary packages:

To have access for all types of NubeSDK, install the typescript and the package @tiendanube/nube-sdk-types, this could be a development dependency.

npm install -D typescript @tiendanube/nube-sdk-types

If you are going to develop an application with a user interface, install the package @tiendanube/nube-sdk-ui:

npm install @tiendanube/nube-sdk-ui

And if you want to use JSX/TSX syntax, also install @tiendanube/nube-sdk-jsx:

npm install @tiendanube/nube-sdk-jsx

Now you need to create a module that holds the App's entrypoint, we usually use main.ts or main.tsx.

// main.ts
import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export async function App(nube: NubeSDK) {
  // your code
}

This is our recommended typescript compilerOptions

{
  "compilerOptions": {
    "target": "esnext",
    "jsx": "react-jsx",
    "jsxImportSource": "@tiendanube/nube-sdk-jsx/dist", // ONLY IF YOU USE JSX
    "module": "commonjs",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true
  }
}

To build your script, we recommend using tsup, which is already preconfigured in our official templates.

npm install -D tsup
//tsup.config.js

import { defineConfig } from "tsup";

export default defineConfig({
  entry: ["src/main.tsx"],
  format: ["esm"],
  target: "esnext",
  clean: true,
  minify: true,
  bundle: true,
  sourcemap: false,
  splitting: false,
  skipNodeModulesBundle: false,
  esbuildOptions(options) { // ONLY IF YOU USE JSX
    options.alias = {
      "@tiendanube/nube-sdk-jsx/dist/jsx-runtime": "@tiendanube/nube-sdk-jsx/jsx-runtime",
    };
  },
  outExtension: ({ options }) => ({
    js: options.minify ? ".min.js" : ".js"
  })
});

Adding script to your application​

Adding the script to your application has the same process that with any other script, the only difference is that you have to enable the Uses Nube SDK flag in the script creation screen, otherwise it will loaded as a classic script and it will fail to work as expected.

info

If the scripts will be inserted into an existing app, please send the app_id to api@tiendanube.com / api@nuvemshop.com.br for enablement. Otherwise, you will need to create a new app.

NubeSDK Flag

info

The "Use NubeSDK" option is currently supported only on the Checkout page. If you select this option for scripts intended for the Store page, the SDK will not work as expected.

Important!

Before adding your script, make sure to run the build process using:

npm run build

Enabling development mode​

Applications created using the create-nube-app CLI tool are already preconfigured for development mode. By running the following command:

npm run dev

A local development server will start on port 8080.

To use development mode, you must first enable it and register a valid development URL in the Partner Portal, under your scripts's configuration settings.

info

After making changes in the Partner Portal, there might be a cache delay before the updates are reflected. Please allow some time for the changes to take effect.

NubeSDK Flag

After starting development mode, developers can confirm that the environment is correctly configured by opening the browser console and executing the following command:

nubeSDK.getState().apps;

If development mode is active, an object similar to the following will be returned:

{
  "1028": {
    "id": "1028",
    "script": "http://localhost:8080/main.min.js",
    "registered": true
  }
}

Ensure that the script attribute of your app contains the URL localhost. This confirms that the environment is properly set up for development.

Next Steps​