NextViper
Log In
HomeDocsPublishing Requirements Guide
Official Ecosystem Specification

Package Structure & Required Files Guide

Everything you need to know before publishing a package or new version to the NextViper Registry: manifest schema, file checklist, folder layout, and validation rules.

Publish a Package NowCreator Dashboard
nextviper publish

1. Package Files Checklist

A NextViper package bundle is an archive containing your source code and metadata files.

Mandatory Files (Required)

Required
  • nextviper.toml (or viper.toml)

    The package manifest defining name, SemVer version, description, authors, license, and entrypoint.

  • src/ source directory & entrypoint

    Contains your module logic (e.g. src/lib.nv or src/main.nv).

  • README.md

    Documentation rendered directly on your package page. Must explain installation, quickstart, and code examples.

  • LICENSE file

    Standard open-source or proprietary license (MIT, Apache-2.0, BSD-3-Clause, etc.).

Recommended Optional Files

Optional
  • .nvignore (or .gitignore)

    Specifies file patterns to exclude from the publication bundle (e.g. test artifacts, `.git`, heavy dataset dumps).

  • tests/ directory

    Automated unit tests run via nextviper test to ensure package stability across platform releases.

  • CHANGELOG.md

    Chronological history of features, bug fixes, and breaking changes for each published SemVer release.

  • examples/ directory

    Ready-to-run sample scripts illustrating how to integrate your module in applications.

2. Canonical Directory Structure

Follow this recommended directory layout for seamless compatibility with the NextViper compiler and package resolver.

my-awesome-package/
├── nextviper.toml            # [MANDATORY] Package manifest (name, version, license)
├── README.md                 # [MANDATORY] Markdown documentation & usage instructions
├── LICENSE                   # [MANDATORY] License text (MIT, Apache-2.0, etc.)
├── .nvignore                 # [OPTIONAL]  Files excluded from package tarball
├── CHANGELOG.md              # [OPTIONAL]  Version history and release notes
│
├── src/                      # [MANDATORY] Source code root
│   ├── lib.nv                # Primary library entrypoint exported to consumers
│   ├── matrix.nv             # Submodule: Matrix algorithms & SIMD kernels
│   └── utils.nv              # Submodule: Helper routines
│
├── tests/                    # [RECOMMENDED] Unit and integration tests
│   ├── test_matrix.nv        # Test cases for matrix multiplication
│   └── test_utils.nv         # Test cases for utility helpers
│
└── examples/                 # [OPTIONAL]  Ready-to-run demonstration scripts
    └── benchmark_demo.nv     # Example benchmarking script

3. nextviper.toml Manifest Specification

The nextviper.toml file is the single source of truth for your package.

Sample nextviper.toml
[package]
name = "fast_matrix"
version = "1.0.0"
description = "Hardware-accelerated SIMD matrix multiplication and tensor utilities"
authors = ["Your Name <you@example.com>"]
license = "MIT"
repository = "https://github.com/username/fast_matrix"
homepage = "https://nextviper.nuratix.com/packages/fast_matrix"
documentation = "https://docs.nextviper.nuratix.com/packages/fast_matrix"
keywords = ["matrix", "simd", "tensor", "math", "numerical"]
category = "numerical"
entry = "src/lib.nv"

[dependencies]
std_math = "^1.0.0"
tensor_core = "^0.4.0"

Manifest Fields Breakdown

FieldTypeRequiredDescription
nameStringYesUnique package identifier (2-64 chars, a-z, 0-9, _, -).
versionStringYesStrict Semantic Versioning (e.g. 1.0.0, 1.2.4).
descriptionStringYesConcise 1-sentence summary of the package capabilities.
licenseStringYesSPDX license identifier (e.g. MIT, Apache-2.0, GPL-3.0).
authorsArray<String>NoCreator name and optional email contact.
repositoryStringNoPublic GitHub / GitLab repository URL.
keywordsArray<String>NoSearch index keywords for registry discoverability.
categoryStringNoCategory (data, ai, numerical, networking, crypto, system, general).
[dependencies]Map<String, String>NoRequired external NextViper packages with SemVer ranges.

4. Registry Validation Rules & Limits

Ensure your package complies with the registry security and stability invariants.

Strict Immutability

Once a version (e.g. 1.0.0) is published, its bundle cannot be modified or replaced. You must increment the version number to publish updates.

Package Ownership

Only the verified author/owner of a package can publish subsequent versions unless organization team members are added.

Size & Format Limits

Maximum archive bundle size is 15 MB. Supported archive formats include .tar.gz, .tgz, and .nvpkg.

5. Generating Developer Access Keys

Publishing requires an authenticated Developer Access Key (starts with nv_...).

1

Open Creator Dashboard

Log in and navigate to /dashboard. Scroll down to the Developer Access Keys management card.

2

Configure Token Options

Enter a descriptive token label (e.g. "MacBook CLI", "GitHub Actions CI") and select the desired key expiration lifetime (30d, 90d, 1y, or never).

3

Generate & Save Token

Click Generate Access Key. Copy your raw token string immediately. For security, full keys are never shown again after creation.

Terminal Setup ExampleBASH / ZSH
export NEXTVIPER_TOKEN="nv_bde2c93c1c9901c249160287e60020b54702eb780493bb9c"
# Or persist in your shell profile (~/.bashrc or ~/.zshrc)

6. Publishing via Terminal CLI

Automate package publishing with the official NextViper CLI tooling.

Step 1: Validate & Test Locally

Verify your package builds cleanly and tests pass before dispatching to the global registry:

# Verify build and test suite
nextviper test
# Test bundle packaging locally without uploading
nextviper publish --dry-run

Step 2: One-Step Cloud Publish

Run nextviper publish. The CLI packages and uploads directly to the live registry:

# Publish public package (asks credentials on first run)
nextviper publish --access public
# Publish private package
nextviper publish --access private
# Automated CI/CD releases with flags
nextviper publish --user $USER --token $NEXTVIPER_TOKEN

7. Publishing New Versions of an Existing Package

How to upgrade existing packages while preserving immutable cryptographic integrity.

1

Bump the Version in nextviper.toml

Increment your version following strict Semantic Versioning rules:

Patch (1.0.0 → 1.0.1)

Backwards-compatible bug fixes and minor internal refactors.

Minor (1.0.0 → 1.1.0)

New features added in a backwards-compatible manner.

Major (1.0.0 → 2.0.0)

Incompatible API breaks or syntax redesigns.

2

Publish via CLI or Dashboard Quick Action

You can release the new version using either method:

CLI Release
nextviper publish
Uploads and notifies package followers automatically.
Dashboard Release Button

Visit /dashboard and click "Publish New Version" next to your owned package.

8. Package Metadata & URL Rules (GitHub, Homepage, Docs)

How external URLs and repository links are validated and rendered across the registry.

Repository URL

Public GitHub/GitLab link. If omitted, no GitHub icon is shown on the package page.

Homepage URL

Project website or showcase. Renders a Homepage link only when a valid URL is provided.

Documentation URL

External documentation portal. If not specified, users reference the package's embedded README.

Clean Visibility Invariant:Package detail pages cleanly hide unused metadata fields. If a package does not specify a GitHub repository or homepage, no placeholder buttons, broken links, or empty icons will clutter the user interface.

Ready to Share Your NextViper Package?

Distribute your libraries, tensors, HTTP middleware, or GPU shaders globally with instant sub-millisecond downloads.

Publish PackageMy Creator Dashboard