Skip to content

Developing NPL on your own machine

Learn how to develop NPL applications locally on your machine with your preferred IDE.

Prerequisites

This track has no prerequisite tracks.

You will need:

You can install the NPL CLI following instructions here.

Setting up your project

Creating a new NPL project

For initial exploration, you can create a new project using the following command. Replace my-project with the name of the folder you want to create:

npl init --project-dir my-project

Then open the created folder in your editor of choice. The code created in that folder by the npl init command contains a simple NPL application modeling a hello world protocol. It's a good starting point to understand how NPL works and how to structure your NPL code.

If your terminal is not in the folder where npl init created the code, navigate to it using the cd command:

cd my-project

Development environment

We currently provide plugins for:

The VS Code and Cursor extensions are based on the NPL language server. If you want to use the language server in another editor, check our forum for unofficial support.

These plugins will prompt you to allow them to create and maintain AI rules. This configuration helps AI agents follow the NPL syntax closely and generate better code. It is stored in the .cursorrules or .github/copilot-instructions.md files.

Running your NPL application

Understanding the NPL Runtime

The NPL Runtime is responsible for running NPL code, managing protocol data, preserving audit trails and exposing interfaces to interact with the NPL code. It is composed of the NPL Engine and the NPL Read Model.

The NPL Engine is the core component that executes the NPL code and manages the protocol data. Other components will be presented in the following tracks.

During development, you will likely upload your NPL directly to a running runtime, but we support other deployment methods as well.

Starting the NPL Runtime

To get started, the docker-compose.yml file provides a DEV_MODE configuration for the engine.

Running the engine in development mode will allow you to interact with the engine with an embedded OIDC provider. This removes the need of having to configure an IAM service. Start the engine using:

docker compose up --wait

The provided configuration runs the NPL Engine in development mode, allowing you to interact with the NPL Engine with an embedded OIDC provider. This removes the need to configure a separate identity service (IAM).

Warning

ENGINE_DEV_MODE is for development purposes only. Running this in production is a huge security risk.

Deploying NPL

Once your runtime is up and running, you use the NPL CLI to deploy NPL code to your engine. The npl.yml file contains a local configuration to deploy to the local engine.

To deploy (or re-deploy) your NPL code to the runtime, run:

npl deploy --clear

The --clear flag makes sure that previous deployments are automatically removed. If you want to upgrade a running application, implement a migration.

Working with your code

Writing NPL

The template created with the npl init command contains a simple NPL application modeling a hello world protocol. It's a good starting point to understand how NPL works and how to structure your NPL code.

Testing your code

To run the unit tests that come with the npl init template from your terminal, use:

npl test

Accessing your application

After a successful deployment, you will find your protocols exposed as a service at http://localhost:12000/swagger-ui/.

The NPL API provides a REST interface to interact with your deployed protocols. To find exposed endpoints, take the following steps:

  1. Open http://localhost:12000/swagger-ui/

  2. Select NPL Application in the dropdown in the top right corner

The demo name that appears in the API service and endpoint path corresponds to an NPL package defined in the source.

The Using your NPL application tutorial explains how to make use of this page and NPL API.

Next steps

Further reading