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 ago.mod
file. If you have a project with agno.mod
file, you can use thegno mod tidy
subcommand to auto-convert it to agnomod.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