How to Build a Wix App with the New Wix CLI: Step-by-Step Tutorial

The Wix CLI is quickly becoming one of the most important tools for serious Wix developers. If you want to build reusable solutions for multiple sites, create internal tools for client projects, or even prepare an app for the Wix App Market, learning the new Wix CLI is one of the smartest investments you can make right now.

In this tutorial, we are going to walk through the full process of building a Wix CLI app from scratch, while also recreating a practical demo: a coupon countdown widget that lets a site owner paste in a coupon code and automatically display a live countdown to the coupon’s expiration date on their Wix site. Along the way, we will cover the real-world development flow, the app structure, how to generate extensions, how to test in dev mode, how to debug common Wix CLI issues, how to work with the Wix JavaScript SDK, how to use AI inside your IDE, and how to release your app when you are done.

If you have been searching for a practical guide to Wix CLI app development, how to build a custom Wix app, how to create a Wix site widget with the CLI, or how to use the new Wix CLI with AI, this is the tutorial.

Why the new Wix CLI matters now

The Wix CLI is not just another developer convenience tool. It is becoming central to the future of Wix app development.

For a long time, developers had multiple ways to build Wix apps. You could self-host, you could use Wix Blocks, or you could use more code-driven approaches. But the landscape is changing. Wix has been signaling that Blocks is no longer the long-term focus, especially for newer environments like Wix Harmony, and that makes the new Wix CLI one of the most important ways to build apps that will remain broadly compatible moving forward.

What makes the CLI especially attractive is that it gives you a streamlined, Wix-hosted way to build applications without having to manage your own infrastructure the same way you would with a traditional self-hosted solution. You still get flexibility, but you also get a smoother developer experience. That makes the Wix CLI especially appealing for agencies, independent developers, product builders, and advanced Wix users who want to create reusable app-based solutions instead of rebuilding similar features from scratch site by site.

This is also why learning the CLI now has leverage. Once you understand the workflow, you can move from building one app to building many.

What we are building in this tutorial

To make this practical, we are not going to stay abstract.

We are going to build a coupon countdown widget app for Wix. The idea is simple: the site owner adds the widget to a page, opens the widget settings, pastes in a coupon code they already created in Wix, and the widget displays a countdown showing how long remains until that coupon expires.

It is a great demo project because it touches a lot of the things that matter in real Wix app development:

• creating a new CLI app

• working with dashboard and site extensions

• generating a custom widget

• adding a settings panel

• connecting app UI to live data

• using the Wix coupons API

• handling permissions

• moving logic to the backend when needed

• fixing CORS issues during development

• releasing the app for installation and distribution

  
  

So even though the end result is a countdown widget, the real value is that you will learn the broader Wix CLI app building process while following a concrete example.

Before you start: what you need installed

Before creating your first Wix CLI app, make sure you have the basics ready.

You will need Node.js, Git, and a Wix account. You will also want an IDE. In the demo workflow, the IDE used is Cursor, mainly because it makes it easy to pair the Wix CLI with AI assistance during development. That is not required, but it is useful. The overall goal in this build is to use as little hand-coding as possible while still understanding what is happening under the hood.

That last part is important. AI can absolutely speed up development, especially with repetitive UI work or boilerplate logic, but the CLI structure still matters. If you do not understand how extensions are wired together, where the config lives, how app permissions work, or where errors are logged, AI will eventually take you off track. This tutorial keeps the workflow approachable without pretending that structure does not matter.

Creating a new Wix CLI app

The first real step is opening your terminal and navigating to the folder where you want the project to live. From there, you run the initialization command:

npm create @wix/new@latest app

This starts the new app creation flow. The CLI will ask whether you want to create a new app or add extensions to an existing app. For this tutorial, we are creating a new basic app, and we give it a name that reflects what we are building: Coupon Countdown.

During setup, the CLI may also ask if you want to configure the Wix MCP for your IDE. In theory, that should help wire your development environment for AI-assisted work with Wix documentation and tools. In practice, it is worth verifying manually later whether it was actually installed and enabled correctly. The setup prompt is helpful, but you should not assume everything is configured perfectly just because the prompt appeared.

Once the project scaffold is created, the CLI begins downloading files and running npm install.

What to do if the initial npm install gets stuck

This is where many first-time developers hit their first snag.

The app generation flow may hang during the install stage, take unusually long, or throw dependency-related errors. That does not necessarily mean the project is dead. A practical workaround is to let the folder get created, open the project directly in your IDE, and then run the install manually yourself:

npm install

Inside the demo build, that manual install flow worked more reliably than waiting for the creation flow to finish everything in one shot. So if you run into issues with the Wix CLI install process, do not panic. Open the generated project and complete the install from there.

Note: If you terminate the app generation flow prematurely, you need to install the skills yourself.

Once the install finishes successfully, you are ready to start understanding the project you just created.

Understanding the Wix CLI project structure

A Wix CLI app is not complicated once you understand the pattern, but there are a few core concepts that matter right away.

The heart of the app lives in the src folder, especially in src/extensions. This is where the different parts of the app are defined. In a generated starter app, the first extension you will usually see is a dashboard extension. Extensions are essentially the different UIs or capabilities your app exposes once it is installed. Depending on what you build, extensions might include dashboard pages, site widgets, plugins, or backend-related functionality.

Each extension generally includes two important pieces:

1. a file that renders the UI

2. a config file that holds metadata such as route path, title, and component mapping

   
   

There is also an extensions.ts file that imports all the app’s extensions and exports them. This file matters more than it may seem. If an extension is not properly wired into that export flow, the app will not recognize it. So whenever something “mysteriously” does not show up, this is one of the first places worth checking.

This is also the stage where you start to realize why AI needs guidance. An AI tool may be able to write a component, but unless it understands how the Wix CLI expects extensions to be structured and exported, it can easily generate something that looks correct in isolation but is broken in the actual app.

Running the starter app in dev mode

Once the project is installed, the next step is to see it running.

Start the local development flow with:

npm run dev

The CLI will create or let you choose a development site, install the app there, and then provide URLs for the site, the editor, and the dashboard. Because the starter app initially includes a dashboard page, the easiest place to begin is the dashboard URL. Open that version and inspect the app page that was generated for you.

From there, you can test the live connection between code and output. Change the default page heading in the dashboard component from something generic like “My Page” to “Hello World,” save the file, and you will see the change reflected in the app view. That fast feedback loop is one of the nicest parts of working with the Wix CLI.

You can also update the extension metadata, such as the dashboard page title and route path, by editing the config file. Those changes may not always auto-refresh as instantly as the UI itself, but a quick manual refresh of the dashboard usually reflects them.

Cleaning up names so the app makes sense

Generated project names like “my page” are fine for a starter template, but once you begin building something real, you will want cleaner naming.

In the demo flow, the dashboard page files, config references, and component paths are renamed to match the app’s actual purpose. That is not just an aesthetic move. Renaming teaches you how the app is wired together. If you rename a component file but forget to update the config path or extension import, the page will stop working.

This is one of the best early lessons in Wix CLI development: structure matters. Once you understand that file names, config references, component paths, and exports all point to each other, debugging becomes much easier.

Checking the Wix MCP in your IDE

If you plan to develop with AI assistance, this is a good moment to verify your Wix MCP setup.

In the demo workflow, the MCP was checked inside Cursor’s settings. Even though the CLI setup suggested it would configure the MCP automatically, it was not fully clear whether that happened or whether it had already been installed previously. The practical move is to confirm it manually. If it is missing, install it from the Wix documentation and make sure it is enabled in the IDE.

When it works well, the MCP can help AI tools better understand Wix documentation, app patterns, and platform-specific details. That can reduce hallucinated implementations and make AI more useful inside a Wix CLI app workflow.

Generating the real widget for our app

At this point, we have only worked with a dashboard page. But the actual feature we want is a widget that can be placed on a site page.

To add that, stop the dev process and run:

npm run generate

The CLI will prompt you to choose the type of extension you want to add. For this build, the correct choice is the custom element extension, which is effectively the standard route for building a Wix site widget using the CLI. The element is given a name like countdown widget, and additional files are generated for the widget.

This generation step creates several important pieces:

• a config file for the widget

• the main custom element file that renders the widget UI

• a settings panel file for editor-side configuration

• CSS-related files for the panel experience

  
  

This is where the app starts to feel real.

The settings panel is especially important because it is how the site owner will interact with the widget in the editor. In our case, that panel is eventually going to let them paste in a coupon code.

The first widget bug: a config issue right out of the box

This part is very useful because it shows real debugging, not idealized success.

After generating the widget and trying to run dev mode again, the app hangs while preparing the dashboard. To diagnose the issue, the transcript checks the .wix debug logs and finds that the widget preset is missing a required name property. That missing field in the generated config is what breaks the startup. Adding the missing name fixes it.

This is an excellent example of how new tooling can still have rough edges and why it is worth knowing where Wix CLI crash information lives. When something breaks during build or dev mode, do not just stare at the terminal. Check the debug logs and read the actual error message.

Once that config fix is made, the widget becomes installable in the editor.

Sanity testing the generated widget before changing anything

Before building custom functionality, it is smart to verify that the generated widget works as-is.

In the editor, the widget is added to the site, and the default settings panel is used to change a basic title value. That confirms the panel is working and that the widget correctly updates its UI using the observed attributes pattern. A small manual change is also made directly in the widget’s HTML rendering to prove that live updates are flowing correctly from code to the editor.

This matters because it creates a clean baseline. If you start making custom changes before verifying that the generated widget works, then every future problem becomes ambiguous. Is it your code? The CLI? The generated template? A config issue? A missing dependency? Sanity testing first eliminates a lot of guesswork.

Using AI to build the coupon countdown logic

Now the fun starts.

Instead of hand-coding everything, the build uses an AI agent inside Cursor to implement the coupon countdown feature. The instructions are explicit: update the settings panel so the user can enter a coupon code, use the Wix coupons API, fetch the coupon, and render a countdown in the widget UI. The prompt also tells the agent where the relevant files live and asks it to use the JavaScript SDK instead of wandering off into unrelated APIs.

That level of specificity is important. One of the recurring lessons from the transcript is that AI works much better when you point it to the exact files and exact implementation direction you want. “Build the feature” is too vague. “Put the input in this settings panel file and render the countdown in this widget file using this Wix SDK path” is much stronger.

The AI produces an initial implementation, but it is not perfect. It leaves old “hello world” UI pieces in place and mishandles some of the coupon integration details. That is normal. AI is acting like a very fast junior collaborator, not magic.

Installing the missing Wix package

One of the first issues with the AI-generated code is that it tries to work with the marketing package but does not actually ensure the relevant package is installed. That is fixed manually with:

npm install @wix/marketing

This is another practical lesson. If you know you will need a specific Wix SDK package, it is often worth installing it yourself early rather than assuming the AI or scaffolding will do it for you. The transcript also notes that the package list in package.json is a simple place to confirm what is currently installed.

A key Wix CLI lesson: you do not create the Wix client yourself

The AI also tries to create a Wix client manually in the front end, which is not the right move in this context.

A major advantage of the Wix CLI is that much of the authentication plumbing is already handled for you. In CLI apps, you generally do not need to manually create a Wix client in the front end the same way you might in another architecture. That gets corrected, the leftover demo UI is removed, and the widget becomes much cleaner.

This is one of those platform-specific patterns that AI might miss unless it has strong Wix context. Knowing it yourself will save you a lot of time.

Testing the coupon countdown with a real coupon

To test the feature properly, a real coupon is created in the Wix dashboard. A percentage discount coupon with a code like TEST1234 is created, and an expiration-related setting is configured so the countdown has a real deadline to display. The code is then pasted into the widget settings panel.

At first, the widget reports that the coupon has no valid expiration time. The instinct is to suspect API or code issues, but the debugging process reveals something more mundane: the coupon settings in the dashboard were misunderstood. The coupon UI was set in a way that did not actually apply an end date, even though it looked like one might be present. Once that dashboard configuration is corrected, the widget successfully displays a live countdown.

This is a great reminder that not every bug is a code bug. Sometimes the API is telling the truth and the real issue is simply that the content or dashboard settings are not what you thought they were.

Why it worked in the editor but failed on the live site

The countdown now works in the editor. But once the site is published and viewed on the live frontend, it fails.

This is one of the most important development moments in the whole tutorial.

The reason is permissions. In the editor, you are effectively acting as an admin, so the coupon request succeeds. On the live site, a normal site visitor does not have permission to manage or access coupons in the same way. That means the frontend request fails even though everything appeared correct in the editor.

This is why testing only in the editor is not enough. For any real Wix app, especially one involving data access, roles, or permissions, you need to test on the actual live site environment.

Moving coupon fetching to the backend

To solve the permissions issue, the coupon-fetching logic is moved out of the widget frontend and into a backend HTTP endpoint within the app.

The CLI does not currently generate this endpoint through the same extension generation flow, so the file is created manually in the appropriate app structure. The frontend widget then calls that backend route instead of directly querying coupons itself.

This is the right architectural move for two reasons:

1. it allows sensitive or elevated logic to run on the backend

2. it makes the frontend simpler and safer

   
   

At this stage, the backend endpoint is added and the frontend is rewritten to fetch through it.

Using elevate in the backend

Moving logic to the backend is not enough by itself. The coupons call still needs elevated permissions.

So the backend code is updated to use elevate from Wix Essentials when calling the coupons query. This is what allows the backend function to perform an operation that regular site visitors could not do directly.

If you are building anything in the Wix CLI that needs access beyond normal visitor-level permissions, this pattern is one to remember: move the logic to the backend and elevate the relevant operation there.

Fixing the first backend mistake: the missing base API URL

After moving the coupon logic to the backend, another problem appears. The frontend cannot reach the endpoint properly.

The cause turns out to be that the generated request logic did not include the proper base API URL pattern for how the app expects backend routes to be called in this environment. Once that missing piece is added, the request path improves and the earlier 404-style issue is resolved.

Again, this is a very realistic CLI development moment. The architecture may be correct, but one missing path detail can still break the flow.

Solving CORS issues during local development

Now comes one of the most annoying parts of modern development: CORS.

Once the backend route is being hit, CORS errors start showing up because the widget is running in one origin while requests are being made in a development context that does not automatically match the backend origin. The fix involves adding appropriate response headers and an options handler for preflight requests in the backend route.

At first, the allowed origins are set too narrowly for one context, which helps on the live site but still causes issues in the editor. Eventually, the editor’s null origin behavior is accounted for correctly, and the request works there as well.

This section is especially valuable because it shows that Wix CLI local development can involve environment-specific request behavior. The solution is not just “make it work anywhere,” but “understand which origin is calling what and loosen or target the backend response appropriately.”

The app-level permissions trap almost everyone forgets

Even after backend routing and elevate are in place, there is still one more permissions issue.

This is the kind of thing that trips up even experienced developers repeatedly: app-level permissions.

Within a Wix app, it is not enough to elevate an operation in backend code. The app itself must also request the relevant permission from the site owner. In this case, the app needs Manage Coupons permission added from the app dashboard. Once that permission is added to the app configuration, the installation context can grant the right access.

This is a crucial concept in Wix app development. There are effectively multiple permission layers. If something still fails even after you elevate it in the backend, always ask whether the app itself has requested the required capability.

Once that permission is in place and the dev environment is refreshed, the countdown works on the live site, and after the CORS tweaks are finalized, it works in the editor too.

Polishing the widget UI

With the functionality working, the final refinement is design.

The widget’s countdown display is updated to look more modern and sleek. This is actually a good use case for AI inside the development flow. Once the logic is solid, cosmetic improvements like typography, spacing, card styles, or countdown layout are exactly the kind of thing AI can help iterate on quickly. The important part is that design polishing happens after functionality and architecture are stable.

That sequence matters. Make it work, then make it pretty.

Releasing the Wix CLI app

Once the app is tested and working, releasing it is straightforward.

First, create the production build:

npm run build

Then release it:

npm run release

During release, you can add a short internal version note such as “first version.” Once that completes, the app dashboard shows the released version and makes the app available for distribution.

From the distribution area, you can then choose how to use the app:

• install it on your own site

• create a share link for clients or collaborators

• prepare it for publishing to the Wix App Market

  
  

Publishing publicly involves more steps, including marketing assets, pricing, and Wix review time, but for private and internal use, the app can be distributed much more quickly.

Final thoughts on building with the Wix CLI

The most encouraging takeaway from this project is not just that the coupon countdown app works. It is that once the initial learning curve is out of the way, the Wix CLI app development workflow becomes highly repeatable.

In the span of roughly an hour or two, this demo moved from zero to a functioning app with a settings panel, live widget UI, backend endpoint, permissions setup, countdown logic, local dev workflow, debugging process, and release flow. And while there were absolutely some bumps along the way, those bumps are precisely what make this such a useful learning example.

That is the real promise of the new Wix CLI.

Your first app may feel like a lot. But once you understand how the extensions fit together, how dev mode works, when to use frontend versus backend logic, how Wix app permissions behave, and how to guide AI inside the project structure, you stop thinking in terms of one app and start thinking in terms of a repeatable system for building many.

And that is where things get exciting.

Because today it is a coupon countdown widget.

Tomorrow it could be the foundation of your next reusable Wix product.