Local testing guide

How to start testing your Add-on locally, iterate on changes, and make sense of errors

The fastest way to start developing your Add-on is to see what it looks like in the Square Dashboard. To do this, the CLI comes with the square-cli addons dev command to simplify that process. The CLI does the following:

  • Creates a local development server to serve your Add-on
  • Opens your web browser of choice with the correct parameters to launch your local Add-on into the Square Dashboard
  • Runs Typescript typechecking to look for malconfigured code
  • Watches your code for changes, and automatically reloads your Add-on in the Square Dashboard for faster iteration

To perform local testing, you must be added to a feature flag. If you need assistance with being added or if additional issues occur, send an email to dashboard-add-ons-alpha@squareup.com with your request.

To get started, navigate to your Add-on folder, and run the following command:

square-cli add-ons dev

See the CLI Reference for more details.

Local development

Once your local development server is running via the square-cli add-ons dev command, you should see something like this:

 ~/my-add-on > square-cli add-ons dev
[tsc] Starting up tsc...
[dev-server] Launching your add-on...
[dev-server] Your add-on is running at http://localhost:4174

[dev-server] To view your add-on on the Square Dashboard, visit https://squareup.com/dashboard/customers/directory?local_development_config=%7B%22hosted_url%22%3A%22http%3A%2F%2Flocalhost%3A4174%22%2C%22manifest%22%3A%7B%22add_on_id%22%3A%22PLACEHOLDER_DO_NOT_MODIFY%22%2C%22version%22%3A%220.0.0%22%2C%22views%22%3A%5B%7B%22placement%22%3A%22square.dashboard.modal%22%2C%22entry_point%22%3A%22src%2Fviews%2Fmodal.tsx%22%7D%2C%7B%22placement%22%3A%22square.dashboard.blade%22%2C%22entry_point%22%3A%22src%2Fviews%2Fblade.tsx%22%7D%2C%7B%22placement%22%3A%22square.dashboard.customer.view%22%2C%22entry_point%22%3A%22src%2Fviews%2Fcustomer-view.tsx%22%7D%5D%7D%7D
If you reload the Dashboard, you may lose connection to your add-on. Simply navigate to the link above again to reconnect.

[tsc]
12:39:07 PM - Starting compilation in watch mode...


[tsc]
12:39:08 PM - Found 0 errors. Watching for file changes.

Your local Add-on launches the Square Dashboard with a set of query parameters that tell it how to load your local add-on. These might disappear during testing. However, if you reload the page, your Square Dashboard will still attempt to load your local add-on. It will only stop trying to load it if you close your browser tab, or if you open a new browser tab.

There are two different processes running here:

  1. Your development server, via the dev-server logs. This is the server hosting your local add-on. You will see there is a link there to the Square Dashboard too. The CLI will automatically launch you into this URL, navigating away from the page or reloading it may lose your connection to the local Add-on. Simply navigate back to this URL whenever you need to reload your Add-on.
  2. Typechecking, via the tsc command and logs. Your Add-on is written in Typescript. We run the tsc CLI for you to find typechecking errors that may cause your Add-on to stop functioning.

If your Add-on fails to render or load, you may be encountering a build error. Simply double check your terminal to ensure there are build errors in the logs.

Your local Add-on is restricted to running against http://localhost. The Square Dashboard will not load a local Add-on from any other domain.

Watching files for changes

The CLI square-cli add-ons dev command will automatically watch for any code changes while the local server is running. You do not need to restart the CLI or reload your web page. All changes will be instantly visible in the Square Dashboard.

Error handling and debugging

Once your Add-on is up and running with no build errors, you may want to debug for issues or look for errors.

In our Developer Preview, any client-side errors encountered, will be visible in your Developer Tools console. Please look here first for any errors that you may be encountering.

To debug your local Add-on, you may also set up your own console.log commands, and see the output in your Developer Tools console. You may also set up breakpoints in your debugger in your own Add-on code to walk through your code line by line.