### Start Development Server
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/getting-started.md
Commands to initiate the local development environment. These commands trigger file watching and start a static server for bundle delivery.
```bash
npm run dev
yarn dev
pnpm run dev
bun run dev
```
--------------------------------
### Nexo Library: Install and Create Instance
Source: https://context7.com/tiendanube/devhub-apps/llms.txt
Shows how to install the Nexo library using npm and create a new instance for communication with the Nuvemshop admin panel. It includes optional logging configuration.
```typescript
// Install: npm install @tiendanube/nexo
import nexo from "@tiendanube/nexo";
// Create Nexo instance
const instance = nexo.create({
clientId: "123", // Provided by Nuvemshop
log: true, // Enable message logging (optional)
});
export default instance;
```
--------------------------------
### Install Nexo via Package Managers
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/developer-tools/nexo.md
Commands to install the @tiendanube/nexo package using popular JavaScript package managers.
```bash
$ npm install @tiendanube/nexo
```
```bash
$ yarn add @tiendanube/nexo
```
--------------------------------
### Development Setup in Partner Portal
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/getting-started.md
Instructions on how to configure your app in the Partner Portal to enable development mode and testing on a live store.
```APIDOC
## Partner Portal App Configuration
### Description
This section guides you through setting up your application in the Partner Portal to enable development mode, allowing you to test your app on a live store.
### Steps
1. **Create or Configure App**: Go to the [Partner Portal](https://partners.nuvemshop.com.br/) and create a new application or select an existing one.
2. **Enable Scripts Permission**: Navigate to your app's **Basic data** page, find the **Permissions** section, expand **Scripts**, and activate the permission.
3. **Create Script**: On your app's dashboard, go to the **Scripts** section and click **Create script**.
* Fill in the script details.
* Enable the **Uses Nube SDK** flag.
* Enable **development mode**.
* Set the **development URL** to `http://localhost:8080/main.min.js`.
### Important Notes
- **Storefront Support**: NubeSDK is currently supported on the storefront only with the **Patagonia** theme.
- **Checkout Support**: NubeSDK works with any theme on the checkout page.
- **Cache Delay**: After making changes in the Partner Portal, allow some time for updates to reflect due to potential caching.
### Alternative: Local Mode
Consider using the **Local Mode** feature in [NubeSDK DevTools](./devtools#local-mode) to connect your local dev server to any store directly from the Chrome extension, bypassing the need for Partner Portal development URL setup.
```
--------------------------------
### Start Local Development Server with Yarn
Source: https://github.com/tiendanube/devhub-apps/blob/master/README.md
Starts a local development server for Docusaurus. Changes are reflected live without needing to restart the server, facilitating rapid development.
```bash
yarn start
```
--------------------------------
### List all products
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/erp-guide/overview.md
Retrieves a list of all products registered in the store using a GET request.
```bash
curl -X GET https://api.nuvemshop.com/v1/{{store_id}}/products \
-H 'Authentication: bearer {{app_token}}' \
-H 'User-Agent: Your App Name ({{app_id}})' \
-H 'Content-Type: application/json'
```
--------------------------------
### Start Local Development Server
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/devtools.md
Standard command to initiate the local development environment for NubeSDK applications, which is a prerequisite for using Local Mode in DevTools.
```bash
npm run dev
```
--------------------------------
### Install NubeSDK UI Package (npm, Yarn, pnpm, Bun)
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/manual-setup.md
Installs the NubeSDK UI package, which is necessary for developing applications with a user interface.
```npm
npm install @tiendanube/nube-sdk-ui
```
```Yarn
yarn add @tiendanube/nube-sdk-ui
```
```pnpm
pnpm add @tiendanube/nube-sdk-ui
```
```Bun
bun add @tiendanube/nube-sdk-ui
```
--------------------------------
### Install Dependencies with Yarn
Source: https://github.com/tiendanube/devhub-apps/blob/master/README.md
Installs all project dependencies required for Docusaurus development. This is typically the first step after cloning the repository.
```bash
yarn
```
--------------------------------
### GET /products
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/erp-guide/overview.md
Retrieves a list of all products registered in the store.
```APIDOC
## GET /v1/{store_id}/products
### Description
List all products registered in the store.
### Method
GET
### Endpoint
https://api.nuvemshop.com/v1/{store_id}/products
### Parameters
#### Path Parameters
- **store_id** (string) - Required - The unique identifier of the store.
```
--------------------------------
### Create a styled component with NubeSDK
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/styling/complete-example.md
This example shows how to define styles using StyleSheet and styled components. It integrates theme tokens for consistent design and demonstrates rendering the component into the checkout lifecycle.
```tsx
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { styled, StyleSheet, theme } from "@tiendanube/nube-sdk-ui";
import { Box, Button, Text } from "@tiendanube/nube-sdk-jsx";
const styles = StyleSheet.create({
container: {
backgroundColor: theme.color.main.background,
borderRadius: theme.border.radius,
padding: "24px",
},
title: {
color: theme.color.main.foreground,
fontSize: "24px",
fontWeight: "bold",
marginBottom: "16px",
},
});
const StyledButton = styled(Button)`
background-color: ${theme.color.accent};
color: white;
padding: 12px 24px;
border-radius: ${theme.border.radius};
border: 1px solid ${theme.border.color};
transition: all 0.2s;
&:hover {
transform: translateY(-2px);
box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
}
`;
function MyComponent() {
return (
Welcome to NubeSDKGet Started
);
}
export function App(nube: NubeSDK) {
nube.render("before_main_content", );
}
```
--------------------------------
### Build First Feature with NubeSDK
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/getting-started.md
Example implementation of a banner component that renders UI, listens for cart updates, and reads store state using the NubeSDK.
```tsx
import { Box, Text } from "@tiendanube/nube-sdk-jsx";
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { styled } from "@tiendanube/nube-sdk-ui";
const Banner = styled(Box)`
padding: 16px;
background-color: #f0f7ff;
border-radius: 8px;
margin: 12px 0;
`;
function renderBanner(nube: NubeSDK) {
nube.render("before_main_content", (state) => (
Welcome to {state.store?.name ?? "our store"}!
Your cart has {String(state.cart?.items?.length ?? 0)} item(s)
));
}
export function App(nube: NubeSDK) {
renderBanner(nube);
nube.on("cart:update", () => {
renderBanner(nube);
});
const { store } = nube.getState();
console.log("App loaded on store:", store?.name);
}
```
--------------------------------
### Nuvemshop REST API: Manage Products
Source: https://context7.com/tiendanube/devhub-apps/llms.txt
Provides examples for interacting with the Nuvemshop API to list and create products. It specifies the base URL structure and required headers for authentication and content type.
```bash
# List all products
curl -H 'Authentication: bearer ACCESS_TOKEN' \
-H 'User-Agent: MyApp (name@email.com)' \
https://api.tiendanube.com/v1/123456/products
# Create a new product
curl -X POST \
-H 'Authentication: bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (name@email.com)' \
-d '{ "name": "My new product" }' \
https://api.tiendanube.com/v1/123456/products
```
--------------------------------
### Dynamic Product Grid Rendering
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/slots/storefront-slots.md
An advanced example showing how to extract products from page sections and render styled components dynamically based on the current page context.
```tsx
import { Text } from "@tiendanube/nube-sdk-jsx";
import type { NubeSDK, ProductDetails } from "@tiendanube/nube-sdk-types";
import { styled } from "@tiendanube/nube-sdk-ui";
const StyledText = styled(Text)`
color: red;
font-weight: bold;
`;
export function App(nube: NubeSDK) {
const state = nube.getState();
if (state.location.page.type === "home") {
const sections = state.location.page.data?.sections || [];
const allProducts = sections.reduce((acc: ProductDetails[], section) => {
if (section?.products && Array.isArray(section.products)) {
acc.push(...section.products);
}
return acc;
}, []);
nube.render("product_grid_item_image_top_left", () => {
return allProducts.map((product) => (
ID: {product.id.toString()}
));
});
}
}
```
--------------------------------
### Button Component Usage
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/components/button.md
Basic example of how to use the Button component with primary variant and an onClick handler.
```APIDOC
## Button Component Usage
### Description
This example demonstrates the basic usage of the Button component, rendering it with a primary variant and a simple click handler.
### Method
N/A (Component Usage)
### Endpoint
N/A (Component Usage)
### Request Body
N/A (Component Usage)
### Request Example
```typescript
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { Button } from "@tiendanube/nube-sdk-jsx";
function MyComponent() {
return (
);
}
export function App(nube: NubeSDK) {
nube.send("ui:slot:set", () => ({
ui: {
slots: {
after_line_items: ,
},
},
}));
}
```
### Response
N/A (Component Usage)
```
--------------------------------
### Accessing Browser APIs
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/browser-apis.md
Demonstrates how to get an instance of the browser APIs object from the NubeSDK.
```APIDOC
## Accessing Browser APIs
### Description
Obtain an instance of the browser APIs object to interact with browser functionalities asynchronously.
### Method
`nube.getBrowserAPIs()`
### Endpoint
N/A (This is a client-side SDK method)
### Parameters
None
### Request Example
```typescript
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
export function App(nube: NubeSDK) {
const browser = nube.getBrowserAPIs();
// Now you can use browser.asyncLocalStorage, browser.navigate, etc.
}
```
### Response
#### Success Response (200)
- **browser** (object) - An object containing methods to access browser functionalities.
#### Response Example
```json
{
"asyncLocalStorage": { ... },
"asyncSessionStorage": { ... },
"navigate": function(route) { ... },
"postMessageToIframe": function(iframe, message) { ... }
}
```
```
--------------------------------
### Displaying Icons with Nube SDK
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/components/icon.md
This example demonstrates how to use the Icon component within a Nube SDK application. It shows various configurations including basic usage, custom sizes, and custom colors rendered inside a Box component.
```typescript
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { Icon, Box } from "@tiendanube/nube-sdk-jsx";
function MyComponent() {
return (
{/* Basic icon */}
{/* Icon with custom size */}
{/* Icon with custom color */}
{/* Icon with size and color */}
);
}
export function App(nube: NubeSDK) {
nube.send("ui:slot:set", () => ({
ui: {
slots: {
after_line_items: ,
},
},
}));
}
```
--------------------------------
### Button Usage Example
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/components/button.md
Demonstrates how to import and use the Button component with basic properties like 'variant' and 'onClick'. It shows integration within a React component and how to send UI updates using the NubeSDK.
```typescript
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { Button } from "@tiendanube/nube-sdk-jsx";
function MyComponent() {
return (
);
}
export function App(nube: NubeSDK) {
nube.send("ui:slot:set", () => ({
ui: {
slots: {
after_line_items: ,
},
},
}));
}
```
--------------------------------
### Apply Opacity to Theme Colors
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/styling/theme.md
Demonstrates how to use the .opacity() method on theme colors to define background styles with varying transparency levels. This example renders a component with three different opacity settings using the NubeSDK.
```tsx
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { StyleSheet, theme } from "@tiendanube/nube-sdk-ui";
import { Box, Text } from "@tiendanube/nube-sdk-jsx";
const styles = StyleSheet.create({
container: {
gap: "8px",
padding: "16px",
},
heavy: {
backgroundColor: theme.color.accent.opacity(80),
padding: "12px",
},
medium: {
backgroundColor: theme.color.accent.opacity(50),
padding: "12px",
},
light: {
backgroundColor: theme.color.accent.opacity(20),
padding: "12px",
},
});
function MyComponent() {
return (
80% opacity50% opacity20% opacity
);
}
export function App(nube: NubeSDK) {
nube.render("before_main_content", );
}
```
--------------------------------
### Implementing a Box Component in NubeSDK
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/components/box.md
This example demonstrates how to import and use the Box component within a NubeSDK application. It shows a basic implementation where a Box is rendered inside a UI slot.
```typescript
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { Box } from "@tiendanube/nube-sdk-jsx";
function MyComponent() {
return (
{/* children */}
);
}
export function App(nube: NubeSDK) {
nube.send("ui:slot:set", () => ({
ui: {
slots: {
after_line_items: ,
},
},
}));
}
```
--------------------------------
### Styled Component with Media Queries
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/styling/styled-components.md
Demonstrates the use of media queries within the styled() function to create responsive styles. This example applies different background colors and padding to a Box component based on screen width.
```tsx
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { styled } from "@tiendanube/nube-sdk-ui";
import { Box } from "@tiendanube/nube-sdk-jsx";
const ResponsiveBox = styled(Box)`
background-color: red;
padding: 16px;
@media (max-width: 768px) {
padding: 8px;
background-color: blue;
}
@media (min-width: 1024px) {
padding: 24px;
background-color: green;
}
`;
function MyComponent() {
return Responsive content;
}
export function App(nube: NubeSDK) {
nube.render("before_main_content", );
}
```
--------------------------------
### Initialize SDK with page:loaded event
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/events/page-and-lifecycle.md
The page:loaded event is dispatched when the SDK is fully initialized. Use this event to run setup logic or access initial store state.
```typescript
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
export function App(nube: NubeSDK) {
nube.on("page:loaded", (state) => {
console.log("SDK ready", state.store?.name);
});
}
```
--------------------------------
### Example of x-total-count Header for Pagination
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/erp-guide/overview.md
Illustrates the 'x-total-count' header, which provides the total number of items available for a paginated request. This helps in understanding the scope of the data.
```text
x-total-count: 156
```
--------------------------------
### Link Component Usage Example (TypeScript)
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/components/link.md
Demonstrates how to use the Link component for basic navigation, opening links in new tabs, and applying different variants. It also shows how to integrate the component into a Tiendanube app's UI slots.
```typescript
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { Link, Box } from "@tiendanube/nube-sdk-jsx";
function MyComponent() {
return (
{/* Basic link */}
Visit Tiendanube
{/* Link that opens in a new tab */}
Open in new tab
{/* Link with variant */}
Primary link
);
}
export function App(nube: NubeSDK) {
nube.send("ui:slot:set", () => ({
ui: {
slots: {
after_line_items: ,
},
},
}));
}
```
--------------------------------
### Initialize Help Modal in App
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/examples/modal-popup.md
Demonstrates how to integrate the help modal into the main application flow by calling the setupHelpModal utility with specific contact details and configuration.
```tsx
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { setupHelpModal } from "./components/HelpModal";
export function App(nube: NubeSDK) {
setupHelpModal(nube, {
title: "Need Help?",
description: (state) => `Hi ${state.customer?.contact?.name || "there"}! Contact us for questions.`,
contacts: [
{ label: "Instagram", value: "@mystore_official" },
{ label: "WhatsApp", value: "+54 11 2345-6789" }
],
footerText: "We're here to help with shipping or payment methods.",
closeButtonText: "Got it, thanks!",
slot: "corner_bottom_right"
});
}
```
--------------------------------
### Install NubeSDK JSX Package (npm, Yarn, pnpm, Bun)
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/manual-setup.md
Installs the NubeSDK JSX package, required for using JSX/TSX syntax in your project.
```npm
npm install @tiendanube/nube-sdk-jsx
```
```Yarn
yarn add @tiendanube/nube-sdk-jsx
```
```pnpm
pnpm add @tiendanube/nube-sdk-jsx
```
```Bun
bun add @tiendanube/nube-sdk-jsx
```
--------------------------------
### Nexo Instance Creation
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/developer-tools/nexo.md
Demonstrates how to create an instance of the Nexo client with required configuration options.
```APIDOC
## Create a Nexo instance
### Description
Initializes the Nexo client with your application's `clientId` and an optional `log` flag for debugging message transfers.
### Parameters
#### Request Body
- **clientId** (string) - Required - The unique identifier provided by Nuvemshop.
- **log** (boolean) - Optional - Defaults to `false`. Enables logging of message transfers between the app and the admin.
### Request Example
```json
{
"clientId": "123",
"log": true
}
```
### Response
Returns a Nexo instance that can be used for further interactions.
### Response Example
```typescript
import nexo from "@tiendanube/nexo";
const instance = nexo.create({
clientId: "123",
log: true,
});
export default instance;
```
```
--------------------------------
### Connect and Signal Readiness with Nexo in React
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/applications/native.md
This code demonstrates how to connect the React application to the Merchant's Admin using the Nexo SDK and then signal that the app is ready to be displayed. It uses the `connect` and `iAmReady` helpers from Nexo, managing a connection state to show a loading indicator until the connection is established.
```jsx
import { useEffect, useState } from "react";
import { connect, iAmReady } from "@tiendanube/nexo/helpers";
import nexo from "./nexoClient";
const App: React.FC = () => {
const [isConnect, setIsConnect] = useState(false);
useEffect(() => {
connect(nexo).then(async () => {
setIsConnect(true);
iAmReady(nexo);
});
}, []);
if (!isConnect) return
connecting..
;
return
My app
;
};
export default App;
```
--------------------------------
### Install tsup for Building (npm, Yarn, pnpm, Bun)
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/manual-setup.md
Installs tsup, a fast TypeScript bundler, as a development dependency. This is recommended for building your NubeSDK application scripts.
```npm
npm install -D tsup
```
```Yarn
yarn add -D tsup
```
```pnpm
pnpm add -D tsup
```
```Bun
bun add -D tsup
```
--------------------------------
### Nexo Library: Connect and Signal Ready
Source: https://context7.com/tiendanube/devhub-apps/llms.txt
Demonstrates how to establish a connection with the Nuvemshop admin panel using the Nexo library and signal that the app is ready to be displayed. It utilizes React hooks for managing connection state.
```tsx
import { useEffect, useState } from "react";
import { connect, iAmReady } from "@tiendanube/nexo/helpers";
import nexo from "./nexoClient";
function App() {
const [isConnect, setIsConnect] = useState(false);
useEffect(() => {
connect(nexo).then(() => {
setIsConnect(true);
iAmReady(nexo);
});
}, []);
if (!isConnect) return ;
return ;
}
```
--------------------------------
### Install NubeSDK Core Dependencies (npm, Yarn, pnpm, Bun)
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/manual-setup.md
Installs TypeScript and the core NubeSDK types package as development dependencies. This is required for all NubeSDK applications.
```npm
npm install -D typescript @tiendanube/nube-sdk-types
```
```Yarn
yarn add -D typescript @tiendanube/nube-sdk-types
```
```pnpm
pnpm add -D typescript @tiendanube/nube-sdk-types
```
```Bun
bun add -D typescript @tiendanube/nube-sdk-types
```
--------------------------------
### Creating a Production Build
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/getting-started.md
Details the process of generating an optimized production bundle for deployment. Commands for npm, Yarn, pnpm, and Bun are listed. The output is a minified `.min.js` file in the `dist/` folder, ready for upload.
```bash
npm run build
yarn build
pnpm run build
bun run build
```
--------------------------------
### Integrate FAQ Component into Application
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/examples/faq.md
Demonstrates how to instantiate the FAQ component with data and inject it into the UI using the NubeSDK slot system.
```tsx
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { FAQ } from "./components/FAQ";
const faqItems = [
{
question: "What are the shipping options?",
answer: "We offer standard shipping (5-7 business days), express shipping (2-3 business days), and overnight delivery. Shipping costs vary based on your location and the delivery speed selected.",
},
{
question: "What is your return policy?",
answer: "We accept returns within 30 days of purchase. Items must be unused and in their original packaging. To initiate a return, please contact our customer service team.",
}
];
export function App(nube: NubeSDK) {
nube.send("ui:slot:set", () => ({
ui: {
slots: {
after_line_items: ,
},
},
}));
}
```
--------------------------------
### Install Nimbus Core Packages
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/developer-tools/nimbus.md
Commands to install the essential Nimbus styles and components packages using Yarn or NPM. These packages are required to use the Nimbus design system in your project.
```bash
yarn add @nimbus-ds/styles @nimbus-ds/components
```
```bash
npm add @nimbus-ds/styles @nimbus-ds/components
```
--------------------------------
### App Initialization for Product Grid Badges
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/examples/extra-info-product-list.md
This code snippet shows how to integrate the `setupProductGridBadges` function into the main application setup. It imports the necessary function and calls it with the NubeSDK instance, ensuring that the product grid badges are configured when the app initializes.
```tsx
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { setupProductGridBadges } from "./components/ProductGridBadges";
export function App(nube: NubeSDK) {
setupProductGridBadges(nube);
}
```
--------------------------------
### Field Component with onChange Handler Example
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/components/field.md
Provides a practical example of using the Field component with an onChange event handler. It demonstrates how to define a typed handler and log the field's current value.
```tsx
import type {
NubeSDK,
NubeComponentFieldEventHandler,
} from "@tiendanube/nube-sdk-types";
import { Field, Box, Text } from "@tiendanube/nube-sdk-jsx";
function MyComponent(nube: NubeSDK) {
// Typed event handler for field
const handleChange: NubeComponentFieldEventHandler = (event) => {
// event.type is "change"
// event.value is string (current field value)
// event.state is the full NubeSDKState
const fieldValue = event.value ?? "";
console.log("Field value:", fieldValue);
};
return (
Contact Information
);
}
export function App(nube: NubeSDK) {
nube.send("ui:slot:set", () => ({
ui: {
slots: {
after_line_items: MyComponent(nube),
},
},
}));
}
```
--------------------------------
### GET /webhooks
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/erp-guide/overview.md
Retrieve a list of all registered webhooks for the store.
```APIDOC
## GET /webhooks
### Description
Returns a list of all registered webhooks in the store.
### Method
GET
### Endpoint
/webhooks
### Response
#### Success Response (200)
- **webhooks** (array) - List of configured webhook objects.
#### Response Example
[
{
"id": 12345,
"event": "order/created",
"url": "https://yoursystem.com.br/webhook"
}
]
```
--------------------------------
### POST /products
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/erp-guide/overview.md
Creates a new product in the store.
```APIDOC
## POST /v1/{store_id}/products
### Description
Creates a new product in the store. Supports both simple products and products with variations.
### Method
POST
### Endpoint
https://api.nuvemshop.com/v1/{store_id}/products
### Parameters
#### Path Parameters
- **store_id** (string) - Required - The unique identifier of the store.
#### Request Body
- **name** (string) - Required - Product name.
- **price** (number) - Required - Product price.
- **sku** (string) - Optional - Stock Keeping Unit.
### Request Example
{
"name": "Basic T-shirt",
"price": 49.99,
"sku": "CAM-001"
}
```
--------------------------------
### GET /orders
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/erp-guide/overview.md
List all orders placed in the store with optional filtering.
```APIDOC
## GET /orders
### Description
Returns a list of orders placed in the store. The results can be filtered by several parameters.
### Method
GET
### Endpoint
/orders
### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number.
- **per_page** (integer) - Optional - Number of items per page.
- **status** (string) - Optional - Filter by order status (e.g., open, closed, cancelled).
- **created_at_min** (string) - Optional - Minimum creation date (ISO 8601).
- **created_at_max** (string) - Optional - Maximum creation date (ISO 8601).
### Response
#### Success Response (200)
- **orders** (array) - List of order objects.
```
--------------------------------
### GET /products/{product_id}/variants/{variant_id}
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/erp-guide/overview.md
Retrieve details for a specific product variation.
```APIDOC
## GET /products/{product_id}/variants/{variant_id}
### Description
Retrieves the detailed information for a specific product variation using its unique ID. This endpoint provides all attributes and current status of a single variation.
### Method
GET
### Endpoint
`/v1/{store_id}/products/{product_id}/variants/{variant_id}`
### Parameters
#### Path Parameters
- **store_id** (integer) - Required - The ID of the store.
- **product_id** (integer) - Required - The ID of the product associated with the variant.
- **variant_id** (integer) - Required - The ID of the product variation to retrieve.
### Request Example
```bash
curl -X GET "https://api.nuvemshop.com/v1/{store_id}/products/{product_id}/variants/{variant_id}" \
-H "Authentication: Bearer {{app_token}}" \
-H "User-Agent: Your App Name ({{app_id}})"
```
### Response
#### Success Response (200 OK)
- **id** (integer) - The unique identifier for the product variation.
- **price** (number) - The price of the variation.
- **stock** (integer) - The current stock quantity.
- **sku** (string) - The SKU of the variation.
- **attributes** (array) - The attributes defining the variation.
#### Response Example
```json
{
"id": 123,
"price": 120.50,
"stock": 20,
"sku": "SKU-123",
"attributes": [
{
"name": "Size",
"value": "M"
},
{
"name": "Color",
"value": "Blue"
}
]
}
```
```
--------------------------------
### GET /products/{product_id}/variants
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/erp-guide/overview.md
Retrieve a list of all product variations for a specific product.
```APIDOC
## GET /products/{product_id}/variants
### Description
Retrieves a list of all product variations associated with a specific product. This is useful for viewing all available options for an item.
### Method
GET
### Endpoint
`/v1/{store_id}/products/{product_id}/variants`
### Parameters
#### Path Parameters
- **store_id** (integer) - Required - The ID of the store.
- **product_id** (integer) - Required - The ID of the product whose variants are to be listed.
### Request Example
```bash
curl -X GET "https://api.nuvemshop.com/v1/{store_id}/products/{product_id}/variants" \
-H "Authentication: Bearer {{app_token}}" \
-H "User-Agent: Your App Name ({{app_id}})"
```
### Response
#### Success Response (200 OK)
- **id** (integer) - The unique identifier for the product variation.
- **price** (number) - The price of the variation.
- **stock** (integer) - The current stock quantity.
- **sku** (string) - The SKU of the variation.
- **attributes** (array) - The attributes defining the variation.
#### Response Example
```json
[
{
"id": 123,
"price": 120.50,
"stock": 20,
"sku": "SKU-123",
"attributes": [
{
"name": "Size",
"value": "M"
},
{
"name": "Color",
"value": "Blue"
}
]
},
{
"id": 124,
"price": 130.00,
"stock": 15,
"sku": "SKU-123-L-RED",
"attributes": [
{
"name": "Size",
"value": "L"
},
{
"name": "Color",
"value": "Red"
}
]
}
]
```
```
--------------------------------
### Basic Styled Component Creation with styled()
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/styling/styled-components.md
Demonstrates the basic usage of the styled() function to create a new component with custom CSS styles applied to an existing component like Box. It shows how to import necessary modules and render the styled component.
```tsx
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { styled } from "@tiendanube/nube-sdk-ui";
import { Box } from "@tiendanube/nube-sdk-jsx";
const StyledBox = styled(Box)`
background-color: red;
padding: 16px;
border-radius: 8px;
`;
function MyComponent() {
return Custom styled content;
}
export function App(nube: NubeSDK) {
nube.render("before_main_content", );
}
```
```typescript
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { styled } from "@tiendanube/nube-sdk-ui";
import { box } from "@tiendanube/nube-sdk-ui";
const StyledBox = styled(box)`
background-color: red;
padding: 16px;
border-radius: 8px;
`;
export function App(nube: NubeSDK) {
nube.render(
"before_main_content",
StyledBox({
children: "Custom styled content",
}),
);
}
```
--------------------------------
### Create a new product
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/erp-guide/overview.md
Sends a POST request to create a new product in the store. Requires authentication and a JSON payload containing product details like name, price, and SKU.
```bash
curl -X POST https://api.nuvemshop.com/v1/{{store_id}}/products \
-H 'Authentication: bearer {{app_token}}' \
-H 'User-Agent: Your App Name ({{app_id}})' \
-H 'Content-Type: application/json' \
-d '{
"name": "Basic T-shirt",
"description": "100% cotton T-shirt",
"price": 49.99,
"sku": "CAM-001",
"stock": 0,
"inventory_levels": [
{
"location_id": "01GQ2ZHK064BQRHGDB7CCV0Y6N",
"stock": 5
}
],
"categories": [12345],
"images": []
}'
```
--------------------------------
### GET /storefront/slots
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/slots/storefront-slots.md
Retrieves the list of available slots and their associated pages for storefront customization.
```APIDOC
## GET /storefront/slots
### Description
Returns a mapping of available UI slots and the pages where they can be rendered. Note that these slots are only compatible with the Patagonia theme.
### Method
GET
### Endpoint
/storefront/slots
### Parameters
None
### Response
#### Success Response (200)
- **slots** (array) - List of objects containing slot names and supported pages.
#### Response Example
{
"slots": [
{ "name": "before_main_content", "pages": ["home", "product", "category", "search"] },
{ "name": "after_header", "pages": ["home", "product", "category", "search", "cart"] }
]
}
```
--------------------------------
### Use Nexo Store Info and Navigation Helpers
Source: https://context7.com/tiendanube/devhub-apps/llms.txt
Provides utilities to retrieve store metadata, navigate between admin routes, and perform browser-like actions such as clipboard operations. Requires an initialized nexo client instance.
```typescript
import { getStoreInfo, goTo, goToOldAdmin, navigateExit, copyToClipboard, getIsMobileDevice } from "@tiendanube/nexo/helpers";
import nexo from "./nexoClient";
const storeInfo = await getStoreInfo(nexo);
goTo(nexo, "/products");
goToOldAdmin(nexo, "/products");
navigateExit(nexo);
await copyToClipboard(nexo, "text to copy");
const isMobile = await getIsMobileDevice(nexo);
```
--------------------------------
### Get Session Token
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/developer-tools/nexo.md
Provides a utility to retrieve a JWT session token for authenticating requests to your backend.
```APIDOC
## Get Session Token
### Description
Obtain a JSON Web Token (JWT) using the `getSessionToken` helper. This token is signed with your application's Client Secret and can be used to authenticate requests made to your backend, verifying the request's origin.
### Method
`getSessionToken(nexoInstance)`
### Parameters
- **nexoInstance**: The initialized Nexo client instance.
### Request Example
```typescript
import axios from "axios";
import { getSessionToken } from "@tiendanube/nexo/helpers";
import nexo from "./nexoClient"; // Assuming nexoClient.ts exports the Nexo instance
const axiosInstance = axios.create({
baseURL: "https://my-backend.com",
});
axiosInstance.interceptors.request.use(async (request) => {
const token = await getSessionToken(nexo);
const bearerToken = `Bearer ${token}`;
request.headers = { ...request.headers, Authorization: bearerToken };
return request;
});
export default axiosInstance;
```
### Authentication
The returned token is a JWT signed with your application's Client Secret, suitable for use in the `Authorization: Bearer ` header.
```
--------------------------------
### Define Store Feature Payload and Response
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/developer-tools/nexo.md
Example structures for requesting the status of a store feature and the corresponding response object.
```json
{
"featureKey": "a_feature_key"
}
```
```json
{
"isFeatureEnabled": true,
"unlimited": false,
"maxUse": 3
}
```
--------------------------------
### Route Synchronization
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/developer-tools/nexo.md
Enables synchronization of your app's navigation state with the browser's URL fragment, using React Router as an example.
```APIDOC
## Enable route synchronization
### Description
This component synchronizes your application's routing with the browser's URL fragment (e.g., `#myroute`). It listens for changes in the app's location and updates the URL, and also listens for URL changes from the admin to navigate within the app. This example uses React Router.
### Usage
Wrap your application's routes with the `NexoSyncRoute` component. Ensure it renders after `iAmReady` has been called.
### Example Component
```jsx
import React, { useEffect } from "react";
import { useLocation, useHistory } from "react-router-dom";
import { ACTION_NAVIGATE_SYNC, NavigateSyncResponse } from "@tiendanube/nexo/actions";
import { syncPathname } from "@tiendanube/nexo/helpers";
import nexo from "./nexoClient";
const NexoSyncRoute = ({ children }) => {
const { pathname, search } = useLocation();
const { push: goTo, replace: replaceTo } = useHistory();
// Update browser URL when app route changes
useEffect(() => {
const path = search ? `${pathname}${search}` : pathname;
syncPathname(nexo, path);
}, [pathname, search]);
// Navigate app when browser URL changes via admin action
useEffect(() => {
const unsubscribe = nexo.suscribe(
ACTION_NAVIGATE_SYNC,
({ path, replace }: NavigateSyncResponse) => {
replace ? goTo(path) : replaceTo(path);
}
);
return unsubscribe;
}, [goTo, replaceTo]);
return children;
}
export default NexoSyncRoute;
```
### Important Note
This component must be rendered after the `iAmReady` signal has been sent to ensure proper synchronization.
```
--------------------------------
### Create Product via Nuvemshop API (Bash)
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/developer-tools/nuvemshop-api.md
This snippet shows how to create a new product in a Nuvemshop store using a curl command. It includes the 'Content-Type' header for JSON data and the product details in the request body. Authentication with an access token and the store ID are required.
```bash
curl -H 'Authentication: bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (name@email.com)' \
-d '{ "name": "Meu novo produto" }' \
https://api.tiendanube.com/v1/123456/products
```
--------------------------------
### Button with onClick Event Handler
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/components/button.md
Detailed example of using the Button component with a custom onClick event handler to display cart information.
```APIDOC
## Button with onClick Event Handler
### Description
This example shows how to implement a detailed `onClick` event handler for the Button component. The handler logs cart information and displays a toast notification with the item count.
### Method
N/A (Component Usage)
### Endpoint
N/A (Component Usage)
### Parameters
#### Event Handler Data
- **event** (object) - Required - The event object passed to the `onClick` handler.
- **type** (string) - The type of event, always "click" for button clicks.
- **state** (NubeSDKState) - The current state of the Nube SDK.
- **value** (string) - Optional value associated with the button.
### Request Body
N/A (Component Usage)
### Request Example
```tsx
import type {
NubeSDK,
NubeComponentButtonEventHandler,
} from "@tiendanube/nube-sdk-types";
import { Button, Box, Text, Toast } from "@tiendanube/nube-sdk-jsx";
function MyComponent(nube: NubeSDK) {
// Typed event handler for button
const handleButtonClick: NubeComponentButtonEventHandler = (event) => {
// event.type is "click"
// event.value is string (optional)
// event.state is the full NubeSDKState
const itemCount = event.state.cart?.items?.length ?? 0;
const storeName = event.state.store?.name ?? "Store";
console.log("Button clicked:", {
type: event.type,
itemCount,
storeName,
});
// Show toast notification
nube.send("ui:slot:set", () => ({
ui: {
slots: {
corner_top_right: (
Cart Info
You have {String(itemCount)} items in your cart
),
},
},
}));
};
return (
Cart Actions
);
}
export function App(nube: NubeSDK) {
nube.send("ui:slot:set", () => ({
ui: {
slots: {
after_line_items: MyComponent(nube),
},
},
}));
}
```
### Response
N/A (Component Usage)
```
--------------------------------
### Connection and Readiness Check
Source: https://github.com/tiendanube/devhub-apps/blob/master/i18n/en/docusaurus-plugin-content-docs/current/developer-tools/nexo.md
Explains how to check if the app can exchange messages with the admin and notify the admin that the app is ready.
```APIDOC
## Check if the app is connected and ready
### Description
Uses the `connect` helper to verify message exchange capability with the Nuvemshop admin and `iAmReady` to signal your application's readiness. It's crucial to listen for `ACTION_NAVIGATE_SYNC` after signaling readiness.
### Method
`connect(nexoInstance)`
`iAmReady(nexoInstance)`
### Parameters
- **nexoInstance**: The initialized Nexo client instance.
### Request Example
```typescript
import { useEffect, useState } from "react";
import { connect, iAmReady } from "@tiendanube/nexo/helpers";
import nexo from "./nexoClient"; // Assuming nexoClient.ts exports the Nexo instance
function App() {
const [isConnect, setIsConnect] = useState(false);
useEffect(() => {
connect(nexo).then(() => {
setIsConnect(true);
iAmReady(nexo);
});
}, []);
if (!isConnect) return ;
return ;
}
```
### Important Note
After calling `iAmReady`, your application must be prepared to receive the `ACTION_NAVIGATE_SYNC` action, which contains the initial route for your app.
```
--------------------------------
### Listening to Cart Update Event - TypeScript
Source: https://github.com/tiendanube/devhub-apps/blob/master/docs/applications/nube-sdk/script-structure.md
Example of how to listen for the 'cart:update' event using the `nube.on` method and log the total cart price to the console.
```typescript
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
export function App(nube: NubeSDK) {
// Listen to cart update event, dispatched every time that the cart is updated
nube.on("cart:update", ({ cart }) => {
// Log the total price of the cart to console
console.log(cart.prices.total);
});
}
```