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 --project-dir 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:

.
├── api
│   └── src
│       ├── main
│       │   ├── migration.yml
│       │   ├── npl
│       │   │   └── demo
│       │   │       └── helloWorld.npl
│       │   └── rules
│       │       └── rules.yml
│       └── test
│           └── npl
│               └── demo
│                   └── test-hello-world.npl
├── docker-compose.yml
├── npl.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)
  • npl.yml: Configuration file providing parameters and convenience when using the NPL CLI

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

CLI configuration

The npl.yml file contains configuration settings for the NPL CLI. It specifies the project structure and deployment targets (local or cloud), offering an alternative to command-line arguments for many of the CLI commands. In particular, the npl.yml file created by npl init contains the configuration to deploy NPL sources to a local NPL Engine using the npl deploy CLI command. With the settings of this file, deployment proceeds using alice, a user pre-populated when the NPL Engine runs in development mode:

structure: # Configuration for project structure
  sourceDir: api/src/main
  migration: api/src/main/migration.yml

local: # Configuration for deploying to a local NOUMENA Engine instance
  managementUrl: 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

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

Type npl help and visit the NPL CLI documentation for more information on commands, command-line parameters and the configuration file.