# Packages

A Gizlang package is a folder with a `package.json` manifest. The manifest pins every source by
SHA-256, so a build reads exactly the bytes that you reviewed.

:::status{of="packages"}
:::

## The manifest

```json
{
  "name": "geo",
  "version": "1.0.0",
  "gizlang": {
    "version": "0.2.0",
    "entry": { "path": "main.giz", "sha256": "…" },
    "modules": { "shapes": { "path": "shapes.giz", "sha256": "…" } }
  }
}
```

| Field | Meaning |
| --- | --- |
| `gizlang.version` | The toolchain version that builds the package |
| `gizlang.entry` | The main source and its pin |
| `gizlang.modules` | The other sources, by module name, each with its pin |

`giz pin DIR` refreshes the pins after you edit a source.

## Use a package

```sh
giz get . geo@1.0.0
```

`giz get` records the dependency with its exact version and pins, and fetches it from the
GizStack registry.

## Publish a package

Your [terminal token](https://gizstack.com/token) page prints the three settings publication needs. Paste them, then:

```sh
giz publish .
```

- A version is immutable. A yank hides it from new resolutions only.
- Public or private, source or compiled: you choose each one.
- You keep your code and choose its license. The [Gizlang license](https://gizstack.com/license) covers the
  toolchain, not your packages.

## Validate offline

`giz get --frozen DIR` checks a package and its dependencies against their exact pins. It
changes no file, selects no version and uses no network. A missing or edited source fails.

## npm packages

`giz get DIR npm:NAME@SPEC` adds an npm package with its exact version. Installation scripts
never run. [TypeScript and npm](javascript-python.md) shows how a program uses it.

## Playground projects

The [Playground](https://gizstack.com/play) exports an ordinary project: `main.giz` and its pinned `package.json`.
Save both in one folder and run `giz package.json`.