NubeSDK

A development toolkit for creating third-party apps within the Nuvemshop platform.

Important

NubeSDK is currently in its beta phase, and new features are still being implemented. Developers interested in using this SDK should contact the Nuvemshop / Tiendanube team before integration to ensure compatibility and receive support.

About

NubeSDK provides a suite of libraries that enable developers to create secure, declarative, and extensible applications inside the Nuvemshop ecosystem. Apps built with NubeSDK run inside isolated web workers, ensuring a controlled execution environment without direct access to the DOM.

This monorepo contains several key packages that facilitate different aspects of NubeSDK development:

• @tiendanube/nube-sdk-types → TypeScript definitions for NubeSDK.
• @tiendanube/nube-sdk-ui → Functions for building declarative UI components.
• @tiendanube/nube-sdk-jsx → JSX runtime for writing UI components using JSX/TSX.
• create-nube-app → CLI tool for scaffolding and setting up new Nube applications.

Installation

To quickly create a new Nube application, you can use the CLI tool create-nube-app. Simply run the command below, which will scaffold a complete project with all the necessary dependencies:

npm create nube-app@latest

yarn create nube-app

pnpm create nube-app

bun create nube-app

Example Usage

import type { NubeApp } from "@tiendanube/nube-sdk-types";
import { Box, Row, Column, Text, Field } from "@tiendanube/nube-sdk-jsx";

const Component = () => (
  <Box>
    <Row>
      <Column>
        <Text>Hello, NubeSDK!</Text>
      </Column>
    </Row>
    <Field name="email" label="Email" />
  </Box>
);

export const App: NubeApp = (nube) => {
  nube.send("ui:slot:set", () => ({
    ui: {
      slots: {
        before_main_content: <Component />
      }
    }
  }));
}

Example Projects

This repository includes example projects to help you get started quickly:

• Minimal app setup: examples/minimal
• Minimal with UI: examples/minimal-ui
• Minimal with UI in JSX: examples/minimal-ui-jsx

These examples include pre-configured build setups, ensuring a seamless development experience.

Official Documentation

For more details about NubeSDK and how to build apps, check out our official documentation:

NubeSDK Documentation

Contributing

We welcome bug reports and feature requests from the community! See our Contributing Guide for details on how to:

• Report bugs
• Request features
• Ask questions

Releasing an Unstable Version

1. Merge your feature branch into unstable and push
2. A Tiendanube/Nuvemshop team member approves the publish job(s) in CircleCI
3. Install with npm install @tiendanube/nube-sdk-types@unstable

Tip: If unstable is stale, reset it first: git reset --hard origin/main

Releasing a Stable Version

1. Bump the version in the package's package.json
2. Merge to main and push
3. A Tiendanube/Nuvemshop team member approves the publish job(s) in CircleCI

Support

• Questions? Use GitHub Discussions Q&A.
• Found a bug? Open a bug report.
• Feature idea? Open a feature request.
• Changelog: See CHANGELOG.md or follow Announcements for release updates.

---

© Tiendanube / Nuvemshop, 2025. All rights reserved.