mystenlabs/skills

sui-move-project

Move project setup and configuration on Sui.

Ver código-fonte

Como usar

  1. Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
  2. Consulte no original as ferramentas, credenciais e ambientes necessários.
  3. Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/mystenlabs/skills --skill sui-move-project

Antes de começar

  • A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
  • Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Documento original do Skill

Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.

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/ or 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+)

CRITICAL: The Sui framework dependency is automatic. Do NOT add it to Move.toml.

A correct, minimal Move.toml for any Sui Move project is:

toml
[package]
name = "my_project"
edition = "2024"
# No [dependencies] section needed — Sui framework is resolved automatically

This is all you need. The edition = "2024" line tells the CLI to resolve Sui and MoveStdlib automatically. There is no [dependencies] section unless you need third-party or local packages.

Complete working project templates

Always use these exact templates when generating Move projects. Copy them verbatim — do not modify the Move.toml format.

Template: Single Move package with TypeScript client

project/
├── move/
│   ├── Move.toml
│   └── sources/
│       └── my_module.move
└── client/
    ├── package.json
    └── src/
        └── index.ts

move/Move.toml — copy exactly:

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

move/sources/my_module.move — starter pattern:

move
module my_project::my_module;

use sui::event;

public struct MyEvent has copy, drop {
    value: u64,
}

public fun do_something(ctx: &mut TxContext) {
    event::emit(MyEvent { value: 42 });
}

client/package.json — copy exactly:

json
{
  "name": "my-client",
  "type": "module",
  "dependencies": {
    "@mysten/sui": "^2.0.0"
  }
}

client/tsconfig.json — copy exactly:

json
{
  "compilerOptions": {
    "moduleResolution": "nodenext",
    "module": "nodenext",
    "target": "es2022",
    "strict": true
  }
}

Template: Move package with frontend

Same as above, plus a frontend/ directory:

frontend/package.json — copy exactly:

json
{
  "name": "my-frontend",
  "type": "module",
  "dependencies": {
    "@mysten/sui": "^2.0.0",
    "@mysten/dapp-kit-react": "^2.0.0",
    "react": "^19.0.0"
  }
}

Wrong formats that WILL error

All of these are WRONG and will cause build failures:

toml
# WRONG — legacy system name error:
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/testnet" }

# WRONG — version syntax doesn't exist in Move:
sui = { version = "0.34.0" }

# WRONG — local path doesn't exist:
Sui = { local = "../sui-framework" }

# WRONG — implicit dependency error:
sui = { package = "sui", version = "0.1.0" }

Only add [dependencies] when you need third-party or local packages (e.g., MVR or sibling workspace packages). The [environments] section is optional — only add it when deploying to multiple networks (see migration section below).

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

Note: Move.lock is auto-generated — never copy its contents into Move.toml. The git URLs below appear in Move.lock only, not in Move.toml.

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
# This is Move.lock (auto-generated) — NOT Move.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.
do mesmo repositório

Mais Skills

Todos os Skills
mystenlabs
Comunidade

frontend-apps

Builds Sui browser dApps with @mysten/dapp-kit-react (React, Next.js) and @mysten/dapp-kit-core (Vue, Svelte, vanilla JS, Web Components). Use when the user asks how to connect a Sui wallet, add a ConnectButton, set up createDAppKit or DAppKitProvider, read a balance or owned objects/NFTs in a frontend, sign and execute a transaction from a React or Vue component, sponsor gas from a backend, fix a UI that is stale after a transaction, handle Next.js App Router 'use client' / SSR for Sui, migrate

Instalações / 1h
1
GitHub Stars
25
Atualizado
22 de nov.
mystenlabs
Comunidade

naming-conventions

Naming rules for Move smart contracts on Sui - error constants, regular constants, events, capability structs, getter functions, hot potatoes, and dynamic field keys. Use when the user asks to write, scaffold, or review a Move module or Sui smart contract (AMM, liquidity pool, NFT, game profile, inventory, access control, roles, registry), or mentions Move structs, events, error codes, capabilities, getters, or dynamic object fields.

Instalações / 1h
1
GitHub Stars
25
Atualizado
22 de nov.
mystenlabs
Comunidade

sui-bridge

Sui Bridge — the native bridge for the Sui network. Use when explaining how Sui Bridge works, looking up supported assets, querying package IDs or contract addresses, understanding the global limiter, transfer parameters, finality requirements, or governance model. Also use when the user asks about bridging assets between Sui and Ethereum.

Instalações / 1h
1
GitHub Stars
25
Atualizado
22 de nov.
mystenlabs
Comunidade

zklogin

zkLogin on Sui — architecture, protocol flow, integration, and security. Use when explaining how zkLogin works, integrating zkLogin into a Sui application, choosing an OpenID provider, understanding the address derivation scheme, debugging session lifetime or proof issues, or answering questions about zkLogin security properties (salt, ephemeral keys, JWT privacy). Also use when the user asks about OAuth-based wallet-less login on Sui.

Instalações / 1h
1
GitHub Stars
25
Atualizado
22 de nov.