Project files

Source belongs in Src/. Dependencies begin in wax.json and are installed under Packages/.

Project layout

MyApp/
  wax.json
  wax.lock          # after dependencies are resolved
  Src/
    Main.wax
  Packages/

Write your code in Src/. Wax installs dependencies in Packages/, which should not be edited or committed. An application with resolved dependencies commits both wax.json and wax.lock. A new project has no lockfile until add or install resolves its first dependency graph.

A reusable library uses the same structure and may add license material:

MyLibrary/
  wax.json
  LICENSE
  NOTICE          # optional
  Src/

`wax.json`

{
  "name": "MyApp",
  "version": "0.1.0",
  "dependencies": {
    "Easing": {
      "package": "@wax/easing",
      "version": "^1.0.3"
    }
  }
}

Only name and version are required. The other fields are optional:

Field	Meaning
`name`	Project name. Published packages use a valid registry name.
`version`	One exact semantic version, such as `1.4.0`.
`schemaVersion`	Optional manifest schema version. Omit it for the current implicit version `1`; an explicit value must be `1`.
`license`	Optional license metadata. Wax preserves the JSON value but does not interpret or validate it.
`dependencies`	Optional local aliases mapped to package identities and version ranges. Omission means no dependencies.
`app`	Optional compiler app or binary name. It must be a valid C identifier.
`build`	Optional build configuration owned by the compiler. Package commands preserve this object without interpreting it.

Unknown fields are rejected, so a misspelling cannot silently change the meaning of a project. wax add and remove preserve the optional build object when rewriting the manifest.

Package names and aliases

A package name is a lowercase registry name such as easing or @wax/easing.core. An alias is the local name used by your project, such as Easing. Aliases begin with an uppercase ASCII letter and may contain ASCII letters, digits, and underscores.

In an import, the declaration before from is what the file imports. The source after from names a package and may continue with a namespace after ::.

Import from the package root through the current project's alias:

import Curve from Easing;

Or import from a namespace through that alias:

import Curve from Easing::Animation;

An exact registry identity can replace the alias:

import Curve from @Wax/Easing.Core::Animation;

The first two forms use the current project's alias. The third uses a registry name. Package names in Wax source ignore ASCII case before ::; namespace and declaration names remain sensitive to case. Manifests, lockfiles, registry URLs, and installed directory names always use the lowercase registry name.

Each package resolves aliases using its own manifest. An alias does not leak from an application into its dependencies.

Lockfiles in library repositories

A library repository may commit a lockfile for its own tests and example applications. That lock controls those development builds. wax pack does not put the author's wax.lock in the published archive. Consumers resolve the version ranges in the package manifest and record the resulting graph in their own lockfile.

Optional license material

license, LICENSE, and NOTICE are all optional. When present, the manifest value and two regular files are preserved in the package archive and installed source tree. Wax does not infer legal terms, validate the value, or require a license in order to validate or pack a project.

Next, read Versions and lockfiles to see how Wax selects and records package versions.