### Install create-nube-app with NPM

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/create-nube-app/README.md

Use this command to start a new NubeSDK project using NPM.

```sh
npm create nube-app@latest
```

--------------------------------

### Install create-nube-app with Yarn

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/create-nube-app/README.md

Use this command to start a new NubeSDK project using Yarn.

```sh
yarn create nube-app
```

--------------------------------

### Install create-nube-app with PNPM

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/create-nube-app/README.md

Use this command to start a new NubeSDK project using PNPM.

```sh
pnpm create nube-app
```

--------------------------------

### Install @tiendanube/nube-sdk-ui

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/ui/README.md

Install the @tiendanube/nube-sdk-ui package and its peer dependency @tiendanube/nube-sdk-types.

```sh
npm install @tiendanube/nube-sdk-ui @tiendanube/nube-sdk-types
```

--------------------------------

### Interactive create-nube-app Usage Example

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/create-nube-app/README.md

This example demonstrates the interactive prompts when creating a new NubeSDK application, including project naming, template selection, and Git initialization.

```sh
$ npm create nube-app@latest

◆  What is the project's name?
│  my-nube-app
│
◆  Select a template:
│  ● Minimal
│  ○ Minimal with UI
│  ○ Minimal with UI in JSX
│
◇  Initialize git repository?
│  Yes
```

--------------------------------

### Install dependencies

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/nube-devtools/README.md

Install the required project dependencies using npm.

```bash
npm install
```

--------------------------------

### Example Project Structure

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/create-nube-app/README.md

This outlines the typical directory and file structure generated by `create-nube-app` for a new NubeSDK project.

```sh
my-nube-app/
├── .vscode/
│   ├── extensions.json
│   └── settings.json
├── src/
│   ├── main.ts
│   └── main.test.ts
├── .gitignore
├── biome.json
├── package.json
├── README.md
├── tsconfig.json
├── tsup.config.js
└── vitest.config.ts
```

--------------------------------

### Run NubeSDK in development mode

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/examples/age-confirmation.md

Starts a live server for local development of your application.

```bash
npm run dev
```

--------------------------------

### Install @tiendanube/nube-sdk-jsx dependencies

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/jsx/README.md

Install the package along with its required peer dependencies.

```sh
npm install @tiendanube/nube-sdk-jsx @tiendanube/nube-sdk-ui @tiendanube/nube-sdk-types
```

--------------------------------

### Install NubeSDK Types

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/types/README.md

Install the @tiendanube/nube-sdk-types package as a development dependency.

```sh
npm install -D @tiendanube/nube-sdk-types
```

--------------------------------

### Creating a Complete Styled Component

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/styling.md

Example demonstrating the integration of StyleSheet, styled components, and theme tokens in a single component.

```tsx
import { styled, StyleSheet, theme } from "@tiendanube/nube-sdk-ui";
import { Box, Button, Text } from "@tiendanube/nube-sdk-jsx";

// Reusable styles
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",
  },
});

// Static styled component
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);
  }
`;

// Usage
<Box style={styles.container}>
  <Text style={styles.title}>Welcome to NubeSDK</Text>
  <StyledButton>Get Started</StyledButton>
</Box>
```

--------------------------------

### Install Nube SDK UI Package

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Install the Nube SDK UI package if your application has a user interface. This package provides UI components and utilities.

```bash
npm install @tiendanube/nube-sdk-ui
```

```bash
yarn add @tiendanube/nube-sdk-ui
```

```bash
pnpm add @tiendanube/nube-sdk-ui
```

```bash
bun add @tiendanube/nube-sdk-ui
```

--------------------------------

### Run Development Server with npm

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Start the local development server using npm. This server is configured for easy debugging with embedded sourcemaps.

```bash
npm run dev
```

```bash
yarn dev
```

```bash
pnpm dev
```

```bash
bun run dev
```

--------------------------------

### Install Tsup Bundler

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Install tsup as a development dependency for bundling your application. Tsup is a simple and fast bundler recommended for Nube SDK projects.

```bash
npm install -D tsup
```

```bash
yarn add -D tsup
```

```bash
pnpm add -D tsup
```

```bash
bun add -D tsup
```

--------------------------------

### Create Nube App with CLI

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/examples/age-confirmation.md

Use the NubeSDK CLI to create a new application. Ensure Node.js version 16 or higher is installed.

```bash
npm create nube-app@latest
```

--------------------------------

### Install NubeSDK Snippet Package

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/snippet/README.md

Add the package as a development dependency to your project.

```bash
npm install --save-dev @tiendanube/nube-sdk-snippet
```

--------------------------------

### Create a UI Component Tree

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/ui/README.md

Import and use various UI component functions to construct a declarative component tree. This example demonstrates creating a layout with text and an input field.

```ts
import { box, col, row, field, img, txt, fragment } from "@tiendanube/nube-sdk-ui";

const componentTree = box({
  children: [
    row({
      children: [
        col({ children: txt({ children: "Hello, NubeSDK!" }) }),
      ],
    }),
    field({ name: "email", label: "Email" })
  ]
});
```

--------------------------------

### Install Nube SDK Types

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Install the Nube SDK types package as a development dependency. This is required to access NubeSDK types in your project.

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

```bash
yarn add -D typescript @tiendanube/nube-sdk-types
```

```bash
pnpm add -D typescript @tiendanube/nube-sdk-types
```

```bash
bun add -D typescript @tiendanube/nube-sdk-types
```

--------------------------------

### Install Nube SDK JSX Package

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Install the Nube SDK JSX package if you intend to use JSX syntax in your project. This enables JSX transformations and runtime.

```bash
npm install @tiendanube/nube-sdk-jsx
```

```bash
yarn add @tiendanube/nube-sdk-jsx
```

```bash
pnpm add @tiendanube/nube-sdk-jsx
```

```bash
bun add @tiendanube/nube-sdk-jsx
```

--------------------------------

### Listen to Cart Updates with NubeSDK

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/types/README.md

Example of how to use NubeSDK types to listen for cart updates and access the cart state. Requires importing NubeSDK and NubeSDKState types.

```ts
import type { NubeSDK, NubeSDKState } from "@tiendanube/nube-sdk-types";

function App(nube: NubeSDK) {
  nube.on("cart:update", (state: NubeSDKState) => {
    console.log("Cart updated:", state.cart);
  });
}
```

--------------------------------

### Implement Textarea Event Handlers

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/components/textarea.md

Example of handling events using the NubeComponentTextareaEventHandler type.

```tsx
import { Textarea } from "@tiendanube/nube-sdk-jsx";
import type { NubeComponentTextareaEventHandler } from "@tiendanube/nube-sdk-types";

const handleEvents: NubeComponentTextareaEventHandler = (event) => {
  const { type, value, state } = event;
  // Perform some action
};

<Textarea
  name="description"
  label="Description"
  value="example@example.com"
  maxLength={500}
  rows={4}
  onChange={handleEvents}
  onBlur={handleEvents}
  onFocus={handleEvents}
/>;
```

```typescript
import { textarea } from "@tiendanube/nube-sdk-ui";
import type { NubeComponentTextareaEventHandler } from "@tiendanube/nube-sdk-types";

const handleEvents: NubeComponentTextareaEventHandler = (event) => {
  const { type, value, state } = event;
  // Perform some action
};

textarea({
  name: "description",
  label: "Description",
  value: "example@example.com",
  maxLength: 500,
  rows: 4,
  onChange: handleEvents,
  onBlur: handleEvents,
  onFocus: handleEvents,
});
```

--------------------------------

### Accessing NubeSDKState

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/state.md

Demonstrates how to get the current NubeSDKState using the `getState` function and access its properties.

```APIDOC
## Accessing NubeSDKState

### Description
This section shows how to retrieve the current state of the Nube SDK using the `getState` function. This is useful for accessing information when your application starts.

### Method
`getState()`

### Endpoint
N/A (Client-side SDK function)

### Parameters
None

### Request Example
```typescript
import type { NubeSDK, NubeSDKState } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  // Get current state
  const currentState: Readonly<NubeSDKState> = nube.getState();

  // Access state properties
  const cartTotal = currentState.cart.total;
  const storeCurrency = currentState.store.currency;
  const currentPage = currentState.location.page.type;
}
```

### Response
#### Success Response (NubeSDKState)
- **currentState** (Readonly<NubeSDKState>) - An immutable object representing the current state of the Nube SDK.

#### Response Example
```json
{
  "cart": {
    "total": 150.75,
    "items": [...],
    "validation": {}
  },
  "config": {
    "validationRules": {}
  },
  "location": {
    "page": {
      "type": "product",
      "params": {}
    },
    "pathname": "/products/123"
  },
  "store": {
    "currency": "USD",
    "name": "My Store"
  },
  "ui": {
    "slots": {}
  },
  "shipping": null,
  "customer": null,
  "payment": null
}
```
```

--------------------------------

### Button with onClick Handler Accessing State

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/components/button.md

This example demonstrates how to use the onClick handler to access the current SDK state. The handler receives an object containing the event type and the SDK state.

```tsx
import { Button } from "@tiendanube/nube-sdk-jsx";

<Button onClick={({ state }) => {
  // Access the current state
  console.log(state);
  // Perform some action
}}>
  Click here
</Button>;
```

```typescript
import { button } from "@tiendanube/nube-sdk-ui";

button({
  children: "Click here",
  onClick: ({ state }) => {
    // Access the current state
    console.log(state);
    // Perform some action
  }
});
```

--------------------------------

### Get Current App State

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/state.md

Retrieve the current state of the Nube SDK using the `getState` function. This is useful for accessing information when the application starts.

```typescript
import type { NubeSDK, NubeSDKState } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  // Get current state
  const currentState: Readonly<NubeSDKState> = nube.getState();

  // Access state properties
  const cartTotal = currentState.cart.total;
  const storeCurrency = currentState.store.currency;
  const currentPage = currentState.location.page.type;
}
```

--------------------------------

### Scaffold a new Nube application

Source: https://github.com/tiendanube/nube-sdk/blob/main/README.md

Use the CLI tool to initialize a project with all necessary dependencies.

```sh
npm create nube-app@latest
```

```sh
yarn create nube-app
```

```sh
pnpm create nube-app
```

```sh
bun create nube-app
```

--------------------------------

### Build Production App

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Execute the build command to create the production-ready JavaScript file. The output will be located in the `./dist/` directory.

```bash
npx tsup
```

```bash
yarn tsup
```

```bash
pnpm tsup
```

```bash
bunx tsup
```

--------------------------------

### Build NubeSDK for production

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/examples/age-confirmation.md

Creates an optimized version of your script in the dist directory for publication.

```bash
npm run build
```

--------------------------------

### Navigate to project directory

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/nube-devtools/README.md

Change the current working directory to the devtools package folder.

```bash
cd packages/nube-devtools
```

--------------------------------

### Build Production Bundle with npm

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Generate an optimized production bundle for your application using npm. The output script is located in `./dist/main.min.js`.

```bash
npm run build
```

```bash
yarn build
```

```bash
pnpm build
```

```bash
bun run build
```

--------------------------------

### Page Type Validation Utility

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/examples/age-confirmation.md

A utility function to check if the current location in the app is the starting page of the checkout process.

```tsx
import type { AppLocation } from "@tiendanube/nube-sdk-types";

export function isStartPage(location: AppLocation) {
  return location.page.type === "checkout" && location.page.data.step === "start";
}
```

--------------------------------

### Create App Entrypoint

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Define the main application function that accepts the NubeSDK instance. This serves as the entry point for your Nube SDK application.

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

export function App(nube: NubeSDK) {
  // your code here!
}
```

--------------------------------

### App Entry Point with NubeSDK

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

The `App` function in `main.ts` or `main.tsx` is the entry point for your application, providing access to the NubeSDK instance.

```typescript
import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  // your code here!
}
```

--------------------------------

### Field with Event Handlers in JSX

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/components/field.md

Example of using a Field component in JSX with a shared event handler function for onChange, onBlur, and onFocus.

```tsx
import { Field } from "@tiendanube/nube-sdk-jsx";
import type { NubeComponentFieldEventHandler } from "@tiendanube/nube-sdk-types";

const handleEvents: NubeComponentFieldEventHandler = (event) => {
  const { type, value, state } = event;
  // Perform some action 
};

<Field
  name="email"
  label="Email"
  value="example@example.com"
  onChange={handleEvents}
  onBlur={handleEvents}
  onFocus={handleEvents}
/>;
```

--------------------------------

### Define the App entry point in NubeSDK

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/secure-by-design.md

Every application must export an App function which receives the SDK instance for secure communication.

```javascript
export function App(nube) {
  // Your code start here!
}
```

--------------------------------

### Get Item from Session Storage with NubeSDK

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/browser-apis.md

Retrieve a stored value using `asyncSessionStorage.getItem`. The retrieved value is available in the promise's resolution.

```typescript
import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  const browser = nube.getBrowserAPIs();

  browser.asyncSessionStorage.getItem("my_custom_field").then((value) => {
    console.log("my_custom_field", value);
  });
}
```

--------------------------------

### Run Unit Tests with npm

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Use this command to run unit tests for your application using npm. Vitest is preconfigured for testing.

```bash
npm test
```

```bash
yarn test
```

```bash
pnpm test
```

```bash
bun test
```

--------------------------------

### Listen for Cart Updates

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/events.md

The `cart:update` event is dispatched by the store when the cart's content changes. This example logs a message if more than 5 different items are in the cart.

```typescript
nube.on("cart:update", ({ cart }) => {
  if (cart.items.length > 5) {
    console.log("Purchased more than 5 different items");
  }
});
```

--------------------------------

### Initialize App Configuration

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/examples/age-confirmation.md

Configure the application to indicate it performs cart validation. This is done by sending a 'config:set' event.

```tsx
import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.send("config:set", () => ({
    config: {
      has_cart_validation: true,
    },
  }));
}
```

--------------------------------

### Available Scripts in Created Project

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/create-nube-app/README.md

Lists the common npm scripts available in a project generated by `create-nube-app`, covering build, development, testing, linting, and formatting tasks.

```sh
- npm run build
- npm run dev
- npm run test
- npm run test:watch
- npm run test:coverage
- npm run lint
- npm run format
```

--------------------------------

### Validate Cart Content

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/events.md

The `cart:validate` event is dispatched by an app to signal cart validity. It requires `has_cart_validation: true` in the script configuration. This example shows how to reject the cart if it has fewer than 5 items, dispatching a `fail` event, or a `success` event otherwise.

```typescript
// Tell NubeSDK that this script wants to validate the content of the cart
nube.send("config:set", () => ({
  config: {
    has_cart_validation: true
  },
}));

nube.on("cart:update", ({ cart }) => {
  // Reject the cart if it has fewer than 5 items
  if (cart.items.length < 5) {
    // Dispatch a failed `cart:validate` event with the reason why it failed to validate
    nube.send("cart:validate", () => ({
      cart: {
        validation: {
          status: "fail",
          reason: "Cart must have at least 5 items!",
        },
      },
    }));
    return;
  }
  // Dispatch a successful `cart:validate` event
  nube.send("cart:validate", () => ({
    cart: { validation: { status: "success" } },
  }));
});
```

--------------------------------

### Format Code with npm

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Execute this command to format all source code according to project standards using npm. This ensures consistent code style.

```bash
npm run format
```

```bash
yarn format
```

```bash
pnpm format
```

```bash
bun run format
```

--------------------------------

### Implementing Responsive Design

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/styling.md

Use standard CSS media queries within styled components to handle responsive layouts.

```typescript
const ResponsiveContainer = styled(box)`
  padding: 16px;
  flex-direction: column;

  @media (min-width: 768px) {
    padding: 24px;
    flex-direction: row;
  }
`;
```

--------------------------------

### Tsup Bundler Configuration

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Configure `tsup.config.js` for your build process. This configuration specifies entry points, output formats, and optimization settings. Adjust `esbuildOptions.alias` if using JSX.

```javascript
// 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"
  })
});
```

--------------------------------

### config:set

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/events.md

Dispatched by the app to set initial configuration for the integration.

```APIDOC
## EVENT config:set

### Description
Dispatched by the app to setup initial configuration.

### Request Body
- **config** (object) - Required - Configuration object
  - **has_cart_validation** (boolean) - Optional - Enables cart validation feature
  - **disable_shipping_more_options** (boolean) - Optional - Determines whether the user can select a shipping option

### Request Example
```typescript
nube.send("config:set", () => ({
  config: {
    has_cart_validation: true
  },
}));
```
```

--------------------------------

### Set Initial Configuration

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/events.md

Use `config:set` to establish initial configuration for the app. Requires `has_cart_validation` to be set to `true` for cart validation events to function.

```typescript
nube.send("config:set", () => ({
  config: {
    has_cart_validation: true
  },
}));
```

--------------------------------

### Configure and Render a NubeSDK Snippet

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/snippet/README.md

Include the triple-slash reference at the top of the file to enable TypeScript support for injected globals. Use the 'nube.render' method to mount components to the platform.

```tsx
/// <reference types="@tiendanube/nube-sdk-snippet" />

const translations: Readonly<Record<LanguageKey, string>> = {
  pt: "Olá, bem-vindo!",
  es: "Hola, ¡bienvenido!",
  en: "Hi, welcome!"
};

function Greeting({ store }: NubeSDKState) {
  const lang = store.language
  const message = translations[lang]
  return <Text heading={1}>{message}</Text>
}

nube.render("before_main_content", Greeting)
```

--------------------------------

### Implement media queries

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/styling.md

Define responsive styles using standard CSS media queries within styled components.

```typescript
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;
  }
`;
```

--------------------------------

### Button Component Usage

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/components/button.md

Demonstrates the basic usage of the Button component in both JSX and declarative formats.

```APIDOC
## Button Component Usage

### Description
This section shows how to import and use the Button component.

### Usage Examples

#### JSX
```tsx
import { Button } from "@tiendanube/nube-sdk-jsx";

<Button variant="primary" onClick={() => {}}>
  Click here
</Button>;
```

#### Declarative
```typescript
import { button } from "@tiendanube/nube-sdk-ui";

button({
  children: "Click here",
  variant: "primary",
  onClick: () => {},
});
```
```

--------------------------------

### Initialize Textarea Component

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/components/textarea.md

Basic implementation of the Textarea component using JSX or declarative syntax.

```tsx
import { Textarea } from "@tiendanube/nube-sdk-jsx";

<Textarea
  name="description"
  label="Description"
  maxLength={500}
  rows={4}
  onChange={() => {}}
  onBlur={() => {}}
  onFocus={() => {}}
/>;
```

```typescript
import { textarea } from "@tiendanube/nube-sdk-ui";

textarea({
  name: "description",
  label: "Description",
  maxLength: 500,
  rows: 4,
  onChange: () => {},
  onBlur: () => {},
  onFocus: () => {},
});
```

--------------------------------

### Lint Code with npm

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Run this command to lint your code using npm. This helps maintain code quality and consistency.

```bash
npm run lint
```

```bash
yarn lint
```

```bash
pnpm lint
```

```bash
bun run lint
```

--------------------------------

### Listening to State Changes

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/state.md

Explains how to subscribe to state changes using event listeners and receive state snapshots upon event triggers.

```APIDOC
## Listening to State Changes

### Description
This section details how to listen for state changes in the Nube SDK. When a specified event is triggered, the provided listener function will be executed with a snapshot of the SDK's state at that moment.

### Method
`on(event: string, listener: (state: Readonly<NubeSDKState>) => void)`

### Endpoint
N/A (Client-side SDK function)

### Parameters
- **event** (string) - Required - The name of the event to listen for (e.g., 'customer:update', 'cart:update').
- **listener** (function) - Required - A callback function that receives the current state snapshot as an argument.

### Request Example
```typescript
import type { NubeSDK, NubeSDKState } from '@tiendanube/nube-sdk-types';

export function App(nube: NubeSDK) {
  // Listen for state changes
  nube.on('customer:update', (state: Readonly<NubeSDKState>) => {
    const customerEmail = state.customer.email;
    const customerAddress = state.customer.address;
    console.log('Customer updated:', customerEmail, customerAddress);
  });
}
```

### Response
This method does not return a value directly. Instead, it registers a listener that will be invoked when the specified event occurs.

#### Success Response (Callback Invocation)
- The listener function is called with a `Readonly<NubeSDKState>` object representing the state at the time of the event.

#### Response Example (within the listener)
```json
{
  "customer": {
    "email": "test@example.com",
    "address": {
      "street": "123 Main St",
      "city": "Anytown"
    }
  }
}
```
```

--------------------------------

### Check Code Coverage with npm

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Generate a code coverage report using npm. This helps assess the thoroughness of your test suite.

```bash
npm run test:coverage
```

```bash
yarn test:coverage
```

```bash
pnpm test:coverage
```

```bash
bun run test:coverage
```

--------------------------------

### Select shipping method

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/events.md

Dispatches the shipping:select event and listens for success or failure responses.

```typescript
function App (nube: NubeSDK) {
  nube.send("shipping:select", () => ({
    shipping: {
      selected: "ne-correios-sedex",
    }
  }));
  
  nube.on("shipping:select:success", ({ shipping }) => {
    console.log("Selected option", shipping.selected)
  });
  
  nube.on("shipping:select:fail", ({ shipping }) => {
    console.log("Selected option", shipping.selected)
  });
}
```

--------------------------------

### Display an image with responsive sources

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/components/image.md

Provides alternative image sources based on media queries to support different screen sizes.

```tsx
import { Image } from "@tiendanube/nube-sdk-jsx";

function Logo() {
  return (
    <Image
      src="https://hostname/default.png"
      alt="Hello"
      sources={[
        {
          src: "https://hostname/desktop.png",
          media: "(min-width: 769px)",
        },
        {
          src: "https://hostname/mobile.png",
          media: "(max-width: 768px)",
        },
      ]}
    />
  );
}
```

```typescript
import { image } from "@tiendanube/nube-sdk-ui";

function logo() {
  return image({
    src: "https://hostname/default.png",
    alt: "Hello",
    sources: [
      {
        src: "https://hostname/desktop.png",
        media: "(min-width: 769px)",
      },
      {
        src: "https://hostname/mobile.png",
        media: "(max-width: 768px)",
      },
    ],
  });
}
```

--------------------------------

### Run Unit Tests in Watch Mode with npm

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Run unit tests in watch mode using npm. This command automatically re-runs tests when code changes are detected.

```bash
npm run test:watch
```

```bash
yarn test:watch
```

```bash
pnpm test:watch
```

```bash
bun run test:watch
```

--------------------------------

### Listen for Coupon Add Success

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/events.md

The `coupon:add:success` event is dispatched by the store when a coupon is successfully applied to the cart. It logs the applied coupon code.

```typescript
nube.on("coupon:add:success", ({ coupon }) => {
  console.log(`Coupon ${coupon.code} was successfully applied`);
});
```

--------------------------------

### shipping:select Event

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/events.md

This event is dispatched by the `app` to select a shipping method. The store will respond with either `shipping:select:success` or `shipping:select:fail`.

```APIDOC
## `shipping:select`

### Description
Dispatched by `app` to select a shipping method. After dispatching this event, the store will respond with either `shipping:select:success` or `shipping:select:fail`.

### Method
Send (Action Dispatcher)

### Endpoint
`shipping:select`

### Parameters
None

### Request Body
- **shipping** (object) - Required - Shipping details.
  - **selected** (string) - Required - The shipping method to select.
```

--------------------------------

### Integrate Rendering with Event System for State Updates

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/ui-rendering.md

Shows how to render components that interact with SDK events, like validating the cart. It highlights the necessity of manual re-rendering when related state changes occur, involving clearing and re-rendering the slot.

```typescript
export function App(nube: NubeSDK) {
  // Render a component that responds to events
  nube.render("after_line_items", (state) => (
    <Button
      onClick={() => nube.send("cart:validate", () => ({
        cart: { validation: { status: "success" } }
      }))}
    >
      Validate Cart
    </Button>
  ));

  // You need to manually re-render when state changes
  nube.on("cart:validation:updated", () => {
    nube.clearSlot("after_line_items");
    nube.render("after_line_items", (state) => (
      <Button
        onClick={() => nube.send("cart:validate", () => ({
          cart: { validation: { status: "success" } }
        }))}
      >
        Validate Cart
      </Button>
    ));
  });
}
```

--------------------------------

### Store Information

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/state.md

Contains information about the current store, such as its domain, currency, and language settings.

```APIDOC
## `store`

Information about the current store, such as its domain, currency, and language.

```typescript
type Store = {
  domain: string;
  currency: string;
  language: string;
  settings: StoreSettings;
};
```
```

--------------------------------

### Combining Styling Approaches

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/styling.md

Mix StyleSheet for reusable styles and styled() components for static styling definitions.

```typescript
// Reusable styles with StyleSheet
const baseStyles = StyleSheet.create({
  card: {
    backgroundColor: theme.color.main.background,
    borderRadius: theme.border.radius,
    padding: "16px",
  },
});

// Static styles with styled()
const HighlightCard = styled(box)`
  background-color: ${theme.color.accent};
  border: 2px solid ${theme.border.color};
`;
```

--------------------------------

### Display a basic image

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/components/image.md

Renders a standard image using the required src and alt properties.

```tsx
import { Image } from "@tiendanube/nube-sdk-jsx";

function Logo() {
  return <Image src="https://hostname/image.webp" alt="Logo" />;
}
```

```typescript
import { image } from "@tiendanube/nube-sdk-ui";

function logo() {
  return image({ src: "https://hostname/image.webp", alt: "Logo" });
}
```

--------------------------------

### Basic Button Usage

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/components/button.md

Use this snippet to render a basic button with a primary variant and an onClick handler. Ensure the Button component is imported from the appropriate SDK package.

```tsx
import { Button } from "@tiendanube/nube-sdk-jsx";

<Button variant="primary" onClick={() => {}}>
  Click here
</Button>;
```

```typescript
import { button } from "@tiendanube/nube-sdk-ui";

button({
  children: "Click here",
  variant: "primary",
  onClick: () => {},
});
```

--------------------------------

### Define Application Configuration

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/state.md

Defines the application-wide settings for cart validation and shipping options.

```typescript
type AppConfig = {
  /** Determines whether cart validation is enabled. */
  has_cart_validation: boolean;

  /** Determines whether the user can select a shipping option. */
  disable_shipping_more_options: boolean;
};
```

--------------------------------

### Setting Theme Color Opacity

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/styling.md

Apply opacity to theme colors using the .opacity() method with predefined values.

```typescript
import { theme } from "@tiendanube/nube-sdk-ui";

const styles = StyleSheet.create({
  overlay: {
    backgroundColor: theme.color.accent.opacity(50), // 50% opacity
  },
  subtle: {
    backgroundColor: theme.color.main.background.opacity(10), // 10% opacity
  },
  transparent: {
    backgroundColor: theme.color.accent.opacity(0), // 0% opacity
  },
});
```

--------------------------------

### TypeScript Configuration

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/getting-started.md

Configure your `tsconfig.json` file to enable necessary TypeScript features. Ensure `jsx` and `jsxImportSource` are set correctly if using JSX.

```json
{
  "compilerOptions": {
    "target": "esnext",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "jsx": "react-jsx",
    "jsxImportSource": "@tiendanube/nube-sdk-jsx/dist" // only if you use JSX
  }
}
```

--------------------------------

### Define and register a JSX component

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/jsx/README.md

Create a component using JSX syntax and register it to a UI slot via the NubeSDK instance.

```tsx
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { Field } from "@tiendanube/nube-sdk-jsx";

function MyComponent() {
  return (
    <>
      <Field
        label="First Name"
        name="firstname"
        onChange={(e) => {
          console.log(`User first name: ${e.value}`);
        }}
      />
      <Field
        label="Last Name"
        name="lastname"
        onChange={(e) => {
          console.log(`User last name: ${e.value}`);
        }}
      />
    </>
  );
}

export function App(nube: NubeSDK) {
  nube.send("ui:slot:set", () => ({
    ui: {
      slots: {
        after_line_items: <MyComponent />,
      },
    },
  }));
}
```

--------------------------------

### Implement event listeners with TypeScript

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/developer-first.md

Utilize the @tiendanube/nube-sdk-types package for full autocomplete and type safety when handling SDK events.

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

export function App(nube: NubeSDK) {
  nube.on("checkout:ready", ({ store }) => {
    console.log(`Welcome to store ${store.name}`);
  });
}
```

--------------------------------

### onClick Handler Details

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/components/button.md

Explains the structure of the data passed to the onClick handler.

```APIDOC
## onClick Handler

### Description
The `onClick` handler receives an object with event details.

### Handler Signature
```typescript
onClick: (data: {
  type: "click";           // The type of event
  state: NubeSDKState;     // The current state of the SDK
}) => void
```

### Example Usage

#### JSX
```tsx
import { Button } from "@tiendanube/nube-sdk-jsx";

<Button onClick={({ state }) => {
  // Access the current state
  console.log(state);
  // Perform some action
}}>
  Click here
</Button>;
```

#### Declarative
```typescript
import { button } from "@tiendanube/nube-sdk-ui";

button({
  children: "Click here",
  onClick: ({ state }) => {
    // Access the current state
    console.log(state);
    // Perform some action
  }
});
```
```

--------------------------------

### Render Static Component

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/ui-rendering.md

Injects a static component into a specified UI slot. Ensure necessary imports for NubeSDK types and JSX components.

```typescript
import type { NubeSDK } from "@tiendanube/nube-sdk-types";
import { Button, Text } from "@tiendanube/nube-sdk-jsx";

export function App(nube: NubeSDK) {
  // Render a static component
  nube.render("after_line_items", (
    <Button onClick={() => console.log("Clicked!")}>
      Static Button
    </Button>
  ));
}
```

--------------------------------

### Accessing Theme Tokens

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/styling.md

Import the theme object from @tiendanube/nube-sdk-ui to access available design tokens for colors, borders, and component-specific styling.

```typescript
import { theme } from "@tiendanube/nube-sdk-ui";

// Colors
theme.color.accent           // Primary accent color
theme.color.main.foreground  // Main text color
theme.color.main.background  // Main background color

// Borders
theme.border.color           // Default border color
theme.border.radius          // Default border radius

// Component-specific tokens
theme.button.foreground      // Button text color
theme.button.background      // Button background color
theme.button.borderColor     // Button border color
theme.button.borderRadius    // Button border radius

theme.input.border.color     // Input border color

theme.header.foreground      // Header text color
theme.header.background      // Header background color
theme.header.logo.maxWidth   // Header logo max width
theme.header.logo.fontSize   // Header logo font size

theme.footer.foreground      // Footer text color
theme.footer.background      // Footer background color

theme.heading.font           // Heading font family
theme.heading.fontWeight     // Heading font weight
```

--------------------------------

### Field Component Usage

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/components/field.md

Demonstrates basic usage of the Field component in both JSX and declarative UI frameworks.

```APIDOC
## Field Component Usage

### Description
This section shows how to integrate the Field component into your application using either JSX or a declarative UI approach.

### Usage Examples

#### JSX
```tsx
import { Field } from "@tiendanube/nube-sdk-jsx";

<Field
  name="email"
  label="Email"
  onChange={() => {}}
  onBlur={() => {}}
  onFocus={() => {}}
/>;
```

#### Declarative UI
```typescript
import { field } from "@tiendanube/nube-sdk-ui";

field({
  name: "email",
  label: "Email",
  onChange: () => {},
  onBlur: () => {},
  onFocus: () => {},
});
```
```

--------------------------------

### Import NubeSDKState Type

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/state.md

Import the `NubeSDKState` type from the `@tiendanube/nube-sdk-types` package.

```typescript
import type { NubeSDKState } from "@tiendanube/nube-sdk-types";
```

--------------------------------

### Text Component Usage

Source: https://github.com/tiendanube/nube-sdk/blob/main/packages/doc/docs/components/text.md

Demonstrates how to use the Text component in both JSX and declarative TypeScript.

```APIDOC
## Text Component

### Description
The `text` component is used to render text with optional styling. It supports properties such as `color`, `background`, `heading` levels (h1-h6), text formatting `modifiers` (bold, italic, etc.), and inline display.

### Usage Examples

#### JSX
```tsx
import { Text } from "@tiendanube/nube-sdk-jsx";

<Text>Hello World</Text>;
```

#### Declarative TypeScript
```typescript
import { text } from "@tiendanube/nube-sdk-ui";

text({
  text: "Hello World",
});
```

### Properties

| Property   | Type                         | Required | Description                                                             |
| ---------- | ---------------------------- | -------- | ----------------------------------------------------------------------- |
| text       | string                       | Yes      | The text content to be displayed.                                       |
| color      | string                       | No       | The text color (can be CSS variable like "var(--primary-color)").       |
| background | string                       | No       | The background color (can be CSS variable like "var(--primary-color)"). |
| heading    | 1|2|3|4|5|6             | No       | The heading level (h1-h6).                                              |
| modifiers  | TxtModifier[]                | No       | Array of text formatting modifiers.                                     |
| inline     | boolean                      | No       | Whether the text should be displayed inline.                            |

### Property Values

| Type        | Value                                                                                             |
| ----------- | ------------------------------------------------------------------------------------------------- |
| TxtModifier | "bold"<br/>"italic"<br/>"underline"<br/>"strike"<br/>"lowercase"<br/>"uppercase"<br/>"capitalize" |

### Description of Property Values

- **TxtModifier**: Defines possible text formatting modifiers such as bold, italic, underline, strike-through, lowercase, uppercase, and capitalize.
```