Skip to main content

Configuring Gno Projects

Gno supports package configuration through a metadata file called gnomod.toml.

The gnomod.toml file is typically generated using:

gno mod init <pkgpath>

It enables advanced control over how your package is interpreted, deployed, and used on-chain.

Note: Previously, package configuration was done via the gno.mod file - similar to how Go projects are configured with a go.mod file. If you have a project with a gno.mod file, you can use the gno mod tidy subcommand to auto-convert it to a gnomod.toml.

gnomod.toml​

This file defines metadata for your Gno package and can include the following fields:

gno​

Specifies the Gno language version. Currently, only version "0.9" is supported.

pkgpath​

Defines the canonical package path. Must exactly match the path used in the addpkg transaction during deployment (must it right now?).

replace (coming soon)​

Used for local development and testing. When set, this field allows local replacement of the package, but will cause addpkg to fail on-chain. Useful for overriding dependencies during local testing.

creator​

Specifies the address that will be set as the creator of the package (origin of the transaction). This field is used only during genesis (block 0) and replaces the default deployer address if set. Primarily used in monorepo setups. If not specified, it's automatically set to the address that initiated the addpkg transaction.

draft​

A flag intended for chain creators. Marks the package as unimportable during normal operation. This flag is ignored at block 0, allowing draft packages to be included at genesis.

private (coming soon)​

Marks the package as private and unimportable by any other package. Additionally:

  • It can be re-uploaded - the new version fully overwrites the old one.
  • Memory, pointers, or types defined in this package cannot be used or stored elsewhere.
  • Usually, this flag can be used for packages that are meant to be changed, such as the home realm of a specific user (i.e. r/username/home).
  • *This flag does not provide any sort of privacy. All code is still fully open-source and visible to everyone, including the transactions that were used for deployments.

ignore​

Coming soon - follow progress here.

Example​

# gnomod.toml
module = "gno.land/r/test"
gno = "0.9"
draft = true
private = true

[replace]
  old = "gno.land/r/test"
  new = "gno.land/r/test/v2"
[replace]
  old = "gno.land/r/test/v3"
  new = "../.."

[addpkg]
    creator = "g1xyz..."
    height = 123

Note that this example isn't realistic because we should either replace, configure addpkg settings, or do neither, but never both at the same time.

Workspaces with gnowork.toml​

Adding a gnowork.toml file to the root of your workspace allows Gno tooling to better understand your local environment and resolve dependencies between packages. This is especially useful during local development and testing with tools like gno test & gno lint.

Consider the following project structure:

project/
    ├─ p/
    │   └─ library/
    │       ├─ gnomod.toml
    │       └─ lib.gno
    └─ r/
        └─ app/
            ├─ gnomod.toml
            ├─ app.gno
            └─ app_test.gno

In this setup, the app package cannot use library as a dependency during local development. The tooling has no way of knowing that both live inside the same workspace - only dependencies usable are the ones found in gnohome, where the tooling was initially installed.

By adding a gnowork.toml file at the root, Gno tooling can properly link the packages together:

project/
    ├─ gnowork.toml
    ├─ p/
    │   └─ library/
    │       ├─ gnomod.toml
    │       └─ lib.gno
    └─ r/
        └─ app/
            ├─ gnomod.toml
            ├─ app.gno
            └─ app_test.gno

At the moment, gnowork.toml does not have any configuration options and should be an empty file. In the future, workspace-level configuration options may be added to support more advanced use cases.

Gno tooling resolves dependencies by first using the packages available in your workspace. If a dependency cannot be found locally, it will then fall back to other sources, such as a remote chain.

Note: gnowork.toml support is a work in progress for gnodev and gnopls.

Cleaning the dependency cache​

Downloaded dependencies are stored locally under $GNOHOME/pkg/mod/. If you want to remove them and fetch fresh versions, you can run:

gno clean -modcache