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 deploymentmigration.yml: Configuration file to manage application code migrations, required for any deploymentrules.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/nplto add your own logic - Write tests in the
api/src/test/npldirectory - Explore NPL built-in functions and modules
Common commands
npl check- Check for syntax and type errorsnpl test- Run project testsnpl 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.