Move Project Setup

MCP tool: When available in your environment, also query the Sui documentation MCP server (
https://sui.mcp.kapa.ai
) for up-to-date answers. Use it for verification and for details not covered by these reference files.

Source constraint: All information sourced exclusively from docs.sui.io, move-book.com, and MystenLabs/sui-stack-hello-world.

Creating a Move project

Canonical full-stack hello-world project

For an end-to-end Sui developer environment with Move and frontend, use the Sui Stack hello-world repository as the single project root:

bash

git clone https://github.com/MystenLabs/sui-stack-hello-world.git
cd sui-stack-hello-world

Use this existing layout:

sui-stack-hello-world/
├── move/
│   └── hello-world/   # publish this Move package
└── ui/                # run this existing frontend

Do not run

sui move new

, do not create a counter package, and do not run

npm create @mysten/dapp

for this workflow. If current Sui tooling requires a package-management migration, keep the change inside

move/hello-world

and continue deploying the hello-world package.

New project from scratch

Use this only when the user explicitly wants a standalone Move package rather than the full-stack hello-world app.

bash

sui move new my_project
cd my_project

This creates:

my_project/
├── sources/       # .move source files go here
├── tests/         # test files
└── Move.toml      # package manifest

Multi-package workspace layout

When a project contains more than one Move package (for example, a core library and an example or integration package), use a flat

packages/

directory with each package as a sibling:

my_project/
├── packages/
│   ├── core/
│   │   ├── sources/
│   │   ├── tests/
│   │   └── Move.toml
│   └── examples/
│       ├── sources/
│       ├── tests/
│       └── Move.toml
└── ui/

Do not nest packages inside each other (for example, placing

examples/

inside

core/sources/

core/tests/

). Nested package directories trigger test runner bugs such as spurious "address with no value" errors because the toolchain picks up the inner package's

Move.toml

when building the outer one.

To depend on a sibling package, use a

local

path in

Move.toml

toml

# packages/examples/Move.toml
[package]
name = "examples"
edition = "2024"

[dependencies]
core = { local = "../core" }

Move.toml (current format — Sui CLI v1.63+)

The new package management format introduced in Sui CLI v1.63 resolves the Sui framework dependency automatically. You do not need to specify it in

[dependencies]

. A minimal

Move.toml

is:

toml

[package]
name = "my_project"
edition = "2024"

Do not add a

[dependencies]

section for the Sui framework or MoveStdlib — the 2024 edition resolves them automatically. Do not add or suggest a

Sui = { git = "..." }

dependency line — this is a legacy format that errors out on current CLI versions. Only add

[dependencies]

when you need third-party or local packages (e.g., MVR dependencies).

Migrating from
[addresses]
: The old

[addresses]

section with

my_project = "0x0"

is no longer needed and should be removed. If your project previously used

[addresses]

to set package addresses for different networks, replace it with an

[environments]

section that maps environment names to chain IDs:

toml

[environments]
testnet = "4c78adac"
mainnet = "35834a8a"

Module declaration (2024 edition)

With

edition = "2024"

, use single-line module declarations — no curly braces:

move

module my_project::my_module;

// imports, structs, and functions follow at the top level
use sui::object::UID;

Do not use the old curly-brace syntax (

module my_project::my_module { ... }

). The 2024 edition treats the entire file as the module body after the semicolon.

Published.toml and Move.lock

After publishing, the toolchain creates or updates:

Published.toml
: Tracks your published package addresses per environment. Contains
```
published-at
```
and
```
upgrade-capability-id
```
values for each network.
Move.lock
: Auto-generated lock file that pins every resolved dependency to a specific git revision and records manifest digests. Do not edit manually. Commit this to version control.

To publish to a different environment (for example, after publishing to Testnet, now deploying to Devnet), switch environments and publish again. Each network gives the package a separate ID. The

Published.toml

tracks both.

Inspecting Move.lock

Move.lock

contains one

[pinned.<env>.<Dependency>]

section per resolved dependency per environment. Each section records the git source, revision, manifest digest, and dependency graph. Example:

toml

[pinned.testnet.Sui]
source = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "73dd2c..." }
use_environment = "testnet"
manifest_digest = "7AFB6669..."
deps = { MoveStdlib = "MoveStdlib" }

If
```
Move.lock
```
pins a different environment than you expect, or revisions look outdated, delete
```
Move.lock
```
and run
```
sui move build
```
to regenerate it.
If you see build errors after switching networks or updating the CLI, deleting
```
Move.lock
```
and rebuilding often resolves stale-lock issues.

Using MVR dependencies

The Move Registry (MVR) is an onchain package manager for Sui. Install it with:

bash

suiup install mvr

Add an MVR dependency using the CLI:

bash

mvr add @org/package --network testnet

Or declare it directly in

Move.toml

toml

[dependencies]
suins = { r.mvr = "@suins/core" }

The

r.mvr

key tells the resolver to look up the package in the onchain Move Registry instead of fetching from a git URL. Prefer MVR dependencies over git URLs when the package is published to the registry — they are versioned, auditable, and do not depend on git history.

Common dependency and build issues

"Dependency 'Sui' is a legacy system name": Remove the
```
Sui = { git = "..." }
```
line from
```
[dependencies]
```
. The current CLI resolves the Sui framework automatically. This error occurs when using the old git-based dependency format.
"Packages with old dependencies" error: Your CLI version does not match the network. The new package management format introduced in Sui CLI v1.63 changed how dependencies are resolved. Run
```
suiup update sui@testnet
```
then
```
suiup switch sui@testnet
```
to get the latest CLI.
"Cannot upgrade package without having a published id": You need a
```
published-at
```
value in
```
Published.toml
```
to upgrade. This is created automatically after your first
```
sui client publish
```
. If you migrated from the old format, make sure the
```
Published.toml
```
file exists and contains the correct package address.
"Could not determine the correct dependencies": The build requires a
```
--build-env
```
flag or an
```
[environments]
```
section in
```
Move.toml
```
. Add the
```
[environments]
```
section with your target chain IDs.
Edition mismatch: If you get errors about
```
public struct
```
syntax, set
```
edition = "2024"
```
in
```
Move.toml
```
. The
```
legacy
```
edition does not support Move 2024 features like public struct visibility.
Old Move.toml format: If you are using the pre-v1.63 format with
```
[addresses]
```
and
```
published-at
```
inside
```
Move.toml
```
, migrate to the new format: remove
```
[addresses]
```
, add
```
[environments]
```
, and let the toolchain manage
```
Published.toml
```
.

Rules

Use
```
public(package)
```
visibility for non-library functions.
```
public
```
function signatures cannot be deleted or modified in upgrades.
Struct definitions cannot be deleted, modified, or have abilities added through upgrades.
Objects cannot exceed 256 KB. Avoid ever-growing vectors inside objects.

sui-move-project

NPX Install

Tags

SKILL.md Content

Move Project Setup

Creating a Move project

Canonical full-stack hello-world project

New project from scratch

Multi-package workspace layout

Move.toml (current format — Sui CLI v1.63+)

Module declaration (2024 edition)

Published.toml and Move.lock

Inspecting Move.lock

Using MVR dependencies

Common dependency and build issues

Rules