Skip to content

Creating a new NPL project

Learn how to create a new NPL project from scratch and understand its structure.

Prerequisites

  • This track has no prerequisite track
  • NPL CLI installed (see NPL CLI for installation steps)

Initialize a new project

Create a new NPL project using the npl init command:

npl init --projectDir my-project

This command will:

  • Create a new directory called my-project
  • Set up the basic project structure
  • Configure the project with default settings

This project is a simple NPL application and includes the code to run the NPL Engine in development mode. The NPL Engine is the component of the NPL Runtime responsible for executing NPL code and managing protocol instances (read more).

Understanding the project structure

After running npl init, your project will contain:

.
├── .npl
│   └── deploy.yml
├── api
│   └── src
│       ├── main
│       │   ├── migration.yml
│       │   ├── npl
│       │   │   └── demo
│       │   │       └── helloWorld.npl
│       │   └── rules
│       │       └── rules.yml
│       └── test
│           └── npl
│               └── demo
│                   └── test-hello-world.npl
├── docker-compose.yml
└── README.md

Key files and folders in the structure are:

  • npl: NPL sources, required for any deployment
  • migration.yml: Configuration file to manage application code migrations, required for any deployment
  • rules.yml: Configuration file to enable the automatic creation of parties using the attributes in the user's authorization token (optional)
  • deploy.yml: NPL deployment target configurations, required when using the npl deploy CLI command

More details on these files are provided below.

Exploring the code

NPL

The api/src/main/npl/demo/helloWorld.npl file contains a basic Hello World example:

@api
protocol[greeter] HelloWorld() {

    initial state ungreeted;
    final state greeted;

    @api
    permission[greeter] sayHello() returns Text | ungreeted {
        become greeted;
        return "Hello " + getUsername(greeter) + "!";
    };
};

Migration

The api/src/main/migration.yml contains a single changeset describing the current version of NPL. It indicates where to load the npl sources from and specifies the npl version tag.

$schema: https://documentation.noumenadigital.com/schemas/migration-schema-v2.yml

changesets:
  - name: 1.0.0
    changes:
      - migrate:
        dir-list:
          - npl
        rules: rules/rules.yml

Party rules

The migration.yml file points to the rules/rules.yml file containing the party automation rules. Automation rules enable the specification of attributes for the different parties to a protocol. In this example, the rules extract the preferred_username from the protocol creation request's auth token and assign it to the claims of the greeter party on the new HelloWorld protocol instance.

demo.HelloWorld:
  greeter:
    extract:
      claims:
        - preferred_username

Deployment configuration

The .npl/deploy.yml contains the configuration to deploy NPL sources to a local NPL Engine using the npl deploy CLI command. With the default settings of the deploy.yml file, deployment proceeds using alice, a user pre-populated when the NPL Engine runs in development mode:

schemaVersion: v1
defaultTarget: local
targets:
  local:
    type: engine
    engineManagementUrl: http://localhost:12400
    authUrl: http://localhost:11000
    username: alice
    password: password123

Running your project

Navigate to your project directory and run:

cd my-project
docker compose up --wait
npl deploy --sourceDir api/src/main

Next steps

  • Modify the files in api/src/main/npl to add your own logic
  • Write tests in the api/src/test/npl directory
  • Explore NPL built-in functions and modules

Common commands

  • npl check - Check for syntax and type errors
  • npl test - Run project tests
  • npl openapi - Generate an openapi spec