Explanation
How NovaModuleTools thinks about your project
Nova is easiest to use when you understand its model: source files are the inputs, the generated
module in dist/ is the real runtime artifact, and project.json shapes every
workflow from build to release.
Nova treats your project as a buildable module, not a loose script folder
That sounds simple, but it changes how you should work. Instead of importing individual files manually, you let Nova build the project and then validate the generated result.
This is why the normal loop is build → test → import from dist. It keeps the behavior you
validate aligned with the behavior you package, publish, and release later.
Your source tree and your built tree have different jobs
| Area | Purpose | How to think about it |
|---|---|---|
src/ |
Authoring input | Where you edit public functions, private helpers, classes, and resources. |
tests/ |
Project validation | Where Pester tests live for the current project workflow. |
docs/ |
Help and site content | PowerShell help markdown and the end-user site are both part of the finished project experience. |
dist/<ProjectName> |
Generated runtime artifact | This is the module you should import and validate. |
artifacts/ |
Generated reports and package output | This is where test results and package files go. |
project.json is not just metadata
In Nova, project.json is the contract for how your project behaves. It is not only
descriptive. It actively controls:
- recursive discovery
- source markers in generated output
- resource copy layout
- duplicate function validation
- package creation behavior
- raw upload defaults
- Pester output behavior
This is why the configuration reference matters so much: small changes in project.json can
affect how the generated module behaves, how tests are discovered, and what delivery commands do later.
Why package, upload, publish, and release are separate commands
Nova keeps these commands separate so the workflow remains explicit:
- pack creates artifacts
- upload sends existing artifacts to a raw endpoint
- publish publishes the module itself locally or to a PowerShell repository
- release orchestrates build, test, version bump, rebuild, and publish
This separation reduces hidden side effects and makes CI/CD flows easier to reason about.
Why source markers and duplicate-function validation exist
Two settings often surprise new users because they exist to protect maintainability, not just make builds pass:
SetSourcePathadds# Source:markers to the generated module so you can map errors back to the original files.FailOnDuplicateFunctionNamesstops the build when two top-level functions would collide in the generated module.
These settings are enabled by default because they reduce debugging time and help keep the generated module trustworthy.
Why the packaged example matters so much
Many developer tools ship only a minimal hello-world sample. Nova ships a working example project that is meant to act as a living reference for the full workflow.
The example is valuable because it shows the interaction between configuration, source files, tests, resources, packaging, and upload settings all at once.
If you learn well by reading working code, the example project is one of the fastest ways to understand Nova.
How to use this site after you understand the mental model
Once these concepts are clear, use the docs like this:
- go to Core Workflows for the normal daily loop
- go to project.json Reference when changing configuration
- go to Packaging & Delivery when deciding between pack, upload, publish, and release
- go to Troubleshooting when the workflow outcome does not match your expectation