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 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)deploy.yml
: NPL deployment target configurations, required when using thenpl 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 errorsnpl test
- Run project testsnpl openapi
- Generate an openapi spec