Simple NFT Collection Tutorial

This tutorial will guide you through the process of creating a simple NFT collection using Joystiq. We will cover the steps to set up your project, configure the minting UI, and deploy your NFTs.

Prerequisites

Before you begin, ensure you have the following:

• Node.js installed
• Joystiq CLI installed (npm install -g @we-bump/joystiq-cli)
• A Sui wallet set up
• Basic knowledge of NFTs and blockchain concepts
• A set of images or media files for your NFTs

Step 1: Initialize Chain configuration

To interact with the blockchain, you need to create a chain configuration file. This file contains your private key, RPC endpoints, and network information.

joystiq init chain-config

Step 2: Set Up Your Project

Initialize a new Joystiq project.

joystiq init project my-nft-collection

This will create a new directory with the necessary files and structure for your NFT collection.

Step 3: Upload Your NFT Metadata

We need to upload the metadata and media files for your NFTs. For this tutorial, we will use Arweave to store our assets, but you can use any storage solution that suits your needs.

1. First, create an assets directory in your project folder.

mkdir my-nft-collection/assets

2. Next, move your NFT metadata files (JSON) and media files (images) to the assets directory. To generate the metadata files, you can use tools like hashlips.

   a single NFT metadata file should look like this and cannot have any other fields than the following:

   {
       "name":"Lucky",
       "image":"1.png",
       "description":"Lucky is right top",
       "attributes":[
           {
               "trait_type":"lucky",
               "value":"very"
           },
           {
               "trait_type":"direction",
               "value":"top"
           }
       ]
   }

   where image is the name of the image file in the assets directory. and filename should be in the format 1.png, 1.json corresponding to the NFT token ID.

   if you put a -1.json and -1.png, it will be considered as the collection metadata and image, which will be visible on sui explorer.

3. Upload the assets to Arweave using the Joystiq CLI:

joystiq metadata upload my-nft-collection --wallet <path-to-your-arweave-wallet.json>

make sure to replace <path-to-your-arweave-wallet.json> with the path to your Arweave wallet file. and have your wallet funded with enough AR tokens to cover the upload fees.

4. After the upload is complete, you will receive a response with the Arweave transaction ID, the URLs of your uploaded assets and a metadata.json file that contains the metadata for your NFTs in the my-nft-collection directory.

Step 4: Configure the Collection config

Now, we need to configure the collection settings. The cli will generate a config.json file in your project directory. Open this file and modify it according to your collection's requirements. You can refer to the JQ721 config documentation for details on the available fields.

If you have made a -1.json and -1.png, you can set the collection_media_url to the URL of the -1.png file. it should be printed in the console after the upload command.

{
  "collection_name": "test",
  "collection_description": "description",
  "collection_media_url": "https://arweave.net/...",
  "supply": "4444",
  "fixed_metadata": false,
  "royalty_percent": "5",
  "royalty_wallet": "0x...",
  "is_immutable": false,
  "start_order": "1",
  "groups": [
    {
      "name": "public",
      "merkle_root": "0x...",
      "max_mints_per_wallet": "0",
      "reserved_supply": "0",
      "payments": [
        {
          "coin": "0x2::sui::SUI",
          "routes": [
            {
              "method": "transfer",
              "amount": "100001",
              "destination": "0x..."
            }
          ]
        }
      ],
      "start_time": "2025-07-09T06:03:42Z",
      "end_time": null
    },
    {
      "name": "free",
      "merkle_root": null,
      "max_mints_per_wallet": "0",
      "reserved_supply": "0",
      "payments": [],
      "start_time": "2025-07-09T06:03:42Z",
      "end_time": null
    }
  ]
}

If you want to limit who can mint your NFTs, you can set up a whitelist by adding a merkle_root to the group configuration. You can generate the Merkle root using Allowlist documentation. If you don't want to use a whitelist, you can set merkle_root to null.

Step 5: Deploy the Collection

Now that we have configured the collection settings, we can deploy the collection using the Joystiq CLI. Run the following command:

joystiq collection deploy my-nft-collection

This command will create the NFT collection on the blockchain. After the process is complete, you will receive a confirmation message with the collection artifacts json output, which contains the collection address and other details needed for mint-ui configuration.

Step 6: Register Metadata's

Now we need to register the metadata for each NFT in the collection. Run the following command:

joystiq collection metadata set my-nft-collection

This command will register the metadata for each NFT in the collection on the blockchain. After the process is complete, you will receive a confirmation message with the updated metadata information. This may take some time depending on the number of NFTs in your collection.

Step 7: Configure the Mint UI

Now that we have registered the metadata for our NFTs, we need to configure the Mint UI. Firstly clone the mint-ui repository:

git clone git@github.com:joystiqio/joystiq-nft-mint-ui.git

Next, navigate to the cloned directory:

cd joystiq-nft-mint-ui/src

Now, edit the config.json file in the src directory. This file contains the configuration for the mint UI. You can refer to the Launch UI Configuration documentation for details on the available fields.

{
  "name": "my-nft-collection",
  "description": "",
  "website": "",
  "socialX": "",
  "discord": "",
  "rpc": "<rpc url>",
  "network": "<chain>",
  "groups": [
    {
      "name": "public",
       "allowlist": [
        "0x...",
        "0x..."
      ]
    },
    {
      "name": "free",
    }
  ],
  "artifacts": {
    "packageID": "0x...",
    "publisherID": "0x...",
    "collectionObjectID": "0x...",
    "collectionJqCoreConfigID": "0x...",
    "policyID": "0x...",
    "policyCapID": "0x...",
    "displayID": "0x...",
  }
}

Make sure to replace the placeholders with your collection details.

The artifacts section should contain the IDs generated during the deployment of your collection. You can find these IDs in the project folder after the deployment is complete. my-nft-collection/artifacts.json.

If you have set up a whitelist, you can add the addresses to the allowlist field in the groups section. Make sure to use same list of addresses as you generated the Merkle root for, otherwise the minting will fail for those addresses. If you want to add more addresses later, you have to update the Merkle root, update the collection and then update the mint UI configuration.

Step 8: Start the Mint UI

Now that we have configured the Mint UI, we can start it. Run the following command in the joystiq-nft-mint-ui/src directory:

npm install
npm run dev

This will start the Mint UI on your local machine. You can access it by navigating to the url provided in the terminal output. You should now see your NFT collection in the Mint UI, and you can start minting your NFTs. If you want to deploy the Mint UI to a production environment, you can use a hosting service like Vercel or Netlify.

Conclusion

In this tutorial, we have walked through the process of creating a simple NFT collection using Joystiq. You have learned how to configure the collection settings, deploy the collection, register metadata, and set up the Mint UI. With these steps completed, you are now ready to launch your NFT collection and start minting NFTs. If you have any questions or need further assistance, feel free to reach out to the WeBump Discord community.