Getting Started - EXPRESSO Docs

This guide shows you how to start developing for Expresso. You will install the Napps CLI, create a project from a template, start a development session, and connect it to the Napps mobile app.

1. Install the Napps CLI

Install the Napps CLI from npm:

npm install -g @napps/cli

After installing it, you should have the napps command available in your terminal.

2. Create a New Project

Use the Napps project template: Run:

npm create napps@latest

The template will ask you a few questions. Choose the type of project you want to create:

Product Layout
App Extensions

Then give your project a name. After the project is created, go into the project folder:

cd your-project-name

Install the dependencies:

npm install

Set Up Your Own Project

If you prefer to set up your own project instead of using the template, install the Expresso TypeScript types from @napps/component-extension:

npm i @napps/component-extension

This package gives you the TypeScript types for the Expresso APIs, runtime services, app extensions, product data, and supported components.

3. Understand the Project Layout

The generated project contains the files you need to develop and build your Expresso code. An App Extensions project usually looks like this:

your-project-name/
  index.ts
  napps.config.json
  package.json
  tsconfig.json
  vite.config.ts
  src/
    extension.ts

The most important files are:

index.ts: exports the functions that Expresso can load.
src/extension.ts: contains your extension code.
napps.config.json: describes your project, extensions, components, and identifiers.
package.json: contains your dependencies and scripts.
vite.config.ts: contains the build configuration.
tsconfig.json: contains the TypeScript configuration.

For an App Extensions project, you will usually write your logic in src/extension.ts and export it from index.ts. Example:

// src/extension.ts
export const runProductExtension = (products: ProductListingBaseDataEditor[]) => {
  return;
};

// index.ts
import { runProductExtension } from "./src/extension";

export { runProductExtension };

If you choose the Product Layout template, the project is focused on creating components instead of app extension functions. The same idea still applies: write your code in the generated source files, export what the runtime needs from index.ts, and keep the project configuration in napps.config.json. You can later add Product Layout or App Extension to the same project.

4. Start a Development Session

Run:

napps dev

The CLI will start a development session. When prompted, choose the same type of project you selected before:

Choose App Extensions if you created an App Extensions project.
Choose Product Layout if you created a Product Layout project.

The CLI will show you how to connect the mobile app. You can connect by QR code or by direct URL.

5. Install the Napps Mobile App

Install the Napps mobile app on your device. Android: https://play.google.com/store/apps/details?id=pt.napps.shop iOS: https://apps.apple.com/pt/app/napps/id1557222449

6. Connect the App to Your Dev Session

Open the Napps mobile app. Then open the dev menu in the app. From the dev menu, connect to your development session using one of these options:

Scan the QR code shown by napps dev.
Enter the direct URL shown by napps dev.

After the app connects, you can test your Expresso code inside the mobile application.

Next Steps

Now you can edit your project files and continue testing in the app. When you change your code, keep the development session running and follow the CLI output. If the app needs to reconnect, use the QR code or direct URL again.

​1. Install the Napps CLI

​2. Create a New Project

​Set Up Your Own Project

​3. Understand the Project Layout

​4. Start a Development Session

​5. Install the Napps Mobile App

​6. Connect the App to Your Dev Session

​Next Steps