Forem: Igor

MongoDB Atlas Hackathon 2022 - TheSample web3 project for developers and community builders

Igor — Fri, 25 Nov 2022 16:46:32 +0000

What I built

The sample project for web3 enthusiasts, community builders and developers. This project contains of smartcontract (ERC-721) and a website with dashboard and wallet (Metamask) authorization. It can be cloned and used for selling pfp-avatars or NFT collections.

You can check the app link below and try to register using any wallet you want.

Category Submission:

Choose Your Own Adventure

App Link

Link to TheSample project

Screenshots

Main page:

Register form

In the demo you can choose, how to register: admin or not. Dashboards will be different.

Admin dashboard - Users

Admins have access to all users. They can change their state to pending, verified, blocked. Only verified users have access to mint form. User's page also has a search.

Admin dashboard - Settings

Superadmin (specified in .env) can interact with smartcontract and start or stop the sale. Visibility of minting form also depends on that setting.

Superadmin can send emails to all verified users, that the sale has begun.

User dashboard - Home

Users have access to home page, where they can find information about the collection and mint form.

Minting

User dashboard with minted token

Private page for NFT holders

Only NFT holders have access to "Private page".

Provenance page

Page with the provenance hash. Script of the calculating provenance hash is available in the repo.

Description

This project gives you the ability to create and deploy smartcontract, create the list of people, who will be elegible to mint NFT from your collection. After that people will have access to Private page, available only for NFT holders. You can extend the project as you want.

Let's explore users experience.

1) Users get to the site, read the information about your project and collection.

2) Users register using their wallet and fill in all necessary information. After that the dashboard is available for them. From now, users are in the waiting list.

3) Admin need to check the users and make them verified. Users get the email (Mailgun integration), that they were verified.

4) Admin starts the sale. In the Settings tab there is a button for sending emails to all verified users.

5) Users get the email about the sale, go to the dashboard and mint the token.

6) After minting users will get access to Private page

Further steps is up to you!

More information you will find in repositories.

Link to Source Code

Web repo

Smartcontract repo

Permissive License

MIT

Background

I wanted to create a project, that can be useful for web3 developers or community builders even after the hackathon ends.

It might be difficult to organize the sale of NFT collection, especially, if you need universal whitelist, where you can add or remove people at any time. It's very important to unite like-minded people and have the ability to know more about them, before you give them access to your club.

That's why I've made that project. You can easily change it to suit your needs. It contains dashboard for admins to manage users, dashboard for users to mint tokens and get special access to "Private page".

I hope it makes someones life easier 😊

How I built it

This is the first time I was using the MongoDB, and I found it easy-to-start and easy-to-use.

You just need to create Mongo DB and this is it. Table will create automatically after you run the project. For superadmin I added a button "Setup indexes" to add additional indexes.

I used node driver for the project.

Stack and services:

MongoDB for holding users information,
React + Next.js for website navigation,
Solidity + Hardhat for smartcontract,
Python for creating provenance hash
Mailgun for mailer

Additional Resources/Info

Create, deploy and mint smart contract (ERC-721) with NodeJS + Hardhat + Walletconnect + Web3modal

Igor — Fri, 30 Sep 2022 07:52:03 +0000

We will create from scratch ERC-721 smartcontract, deploy it to Ethereum Goerli network using Hardhat + Solidity. For minting we will use NextJs + WalletConnect + Web3Modal

Before we start, I would like to mention, that you can use any network you want. With the help of this article, you can deploy to Mainnet also.

Demo: https://gapon2401.github.io/erc721-mint/
Smartcontract repo (erc721): https://github.com/gapon2401/erc721
Mint page repo (erc721-mint): https://github.com/gapon2401/erc721-mint
Smartcontract: Etherscan Goerli link

We need to go through the following steps to reach our goal:

Creating NFT (ERC-721) smartcontract
Configure hardhat.config.ts and .env
Create deploy function
Create tests
Gas price for deployment and minting the smartcontract
Creating images and metadata for NFT
Deploy and verify smartcontract
Create demo website for minting
(optional) Deep dive and customize

Step 1. Creating NFT (ERC-721) smartcontract

Create new project and install https://hardhat.org - Ethereum development environment. Let's call this project erc721.

In command line run

npx hardhat

Select Create a Typescript project.

In order to continue you will be asked to install some dependencies. The text may vary on the hardhat version.

I will run the following, because I will use yarn:

yarn add -D hardhat@^2.10.2 @nomicfoundation/hardhat-toolbox@^1.0.1

We will use https://www.openzeppelin.com/ template for ERC-721 smartcontract, where all necessary functions have been implemented. You can take a look on it: https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC721/ERC721.sol

Install openzeppelin packages and dotenv:

yarn add -D @openzeppelin/contracts dotenv

Remove everything from the folder contracts and create a file ERC721Contract.sol with the contents:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.14;

import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol";
import "@openzeppelin/contracts/utils/Counters.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract ERC721Contract is ERC721, ERC721URIStorage, Ownable {
    using Counters for Counters.Counter;
    Counters.Counter private _tokenIds;

    // Mint price - 0.1 ETH
    uint256 public constant PRICE = 100000000000000000;

    string private baseURI;

    constructor(string memory _baseTokenURI, string memory _name, string memory _symbol)
    ERC721(_name, _symbol) {
        baseURI = _baseTokenURI;
    }

    /**
     * @notice Contract might receive/hold ETH as part of the maintenance process.
     */
    receive() external payable {}

    /**
     * @notice Mint only for owner
     */
    function mintByOwner(address to, string calldata tokenUri) external onlyOwner
    {
        uint256 newItemId = _tokenIds.current();
        _tokenIds.increment();

        _safeMint(to, newItemId);
        _setTokenURI(newItemId, tokenUri);
    }


    /**
     * @notice Public mint
     */
    function mint() external payable
    {
        require(PRICE <= msg.value, "INVALID_PRICE");

        uint256 newItemId = _tokenIds.current();
        _tokenIds.increment();
        _safeMint(msg.sender, newItemId);

        // Return money, if sender have sent more than 0.1 ETH
        if (msg.value > PRICE) {
            Address.sendValue(payable(msg.sender), msg.value - PRICE);
        }
    }

    /**
     * @notice Read the base token URI
     */
    function _baseURI() internal view override returns (string memory) {
        return baseURI;
    }

    /**
     * @notice Update the base token URI
     */
    function setBaseURI(string calldata uri) external onlyOwner {
        baseURI = uri;
    }

    /**
     * @notice Allow withdrawing funds
     */
    function withdraw() external onlyOwner {
        uint256 balance = address(this).balance;
        Address.sendValue(payable(msg.sender), balance);
    }

    // The following functions are overrides required by Solidity.
    function _burn(uint256 tokenId) internal override(ERC721, ERC721URIStorage) {
        super._burn(tokenId);
    }

    /**
     * @notice Add json extension to all token URI's
     */
    function tokenURI(uint256 tokenId) public view override(ERC721, ERC721URIStorage) returns (string memory)
    {
        return string(abi.encodePacked(super.tokenURI(tokenId), '.json'));
    }
}

If you have any difficulties with the code above, feel free to read more about the Solidity. Here is the summary:

constructor - on deployment we will set the base URI for all tokens, name and a symbol to the token collection.
mintByOwner - is our function, which will create new NFT's for us. Only owner of the contract can call it.
mint - public mint.
setBaseURI - owner of the contract can change the base URI for tokens
withdraw - owner can call this function to transfer money from the contract to it's own wallet address

All other necessary functions are inhereted in this contract from openzeppelin.

The price of the tokens will be 0.1 ETH:

uint256 public constant PRICE = 100000000000000000;

Step 2. Configure hardhat.config.ts and .env

Install the following dependencies in order to escape the errors in developing 😲

yarn add -D ethers @nomiclabs/hardhat-etherscan @typechain/hardhat hardhat-gas-reporter solidity-coverage @types/chai @types/mocha typescript ts-node @nomicfoundation/hardhat-chai-matchers chai @nomicfoundation/hardhat-network-helpers typechain @nomiclabs/hardhat-waffle @typechain/ethers-v5 @nomiclabs/hardhat-ethers

Now configure your hardhat.config.ts:

import * as dotenv from "dotenv";

import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox";

import "./tasks/deploy";

dotenv.config();

const config: HardhatUserConfig = {
  solidity: {
    version: "0.8.14",
    settings: {
      metadata: {
        bytecodeHash: "none",
      },
      optimizer: {
        enabled: true,
        runs: 200,
      },
    },
  },
  networks: {
    goerli: {
      url: process.env.GOERLI_URL,
      accounts:
        process.env.PRIVATE_KEY !== undefined ? [process.env.PRIVATE_KEY] : [],
    },
    mainnet: {
      url: process.env.MAINNET_URL,
      accounts:
        process.env.PRIVATE_KEY !== undefined ? [process.env.PRIVATE_KEY] : [],
    },
  },
  gasReporter: {
    enabled: !!process.env.REPORT_GAS,
  },
  etherscan: {
    apiKey: process.env.ETHERSCAN_API_KEY,
  },
};

export default config;

What do we have here:

solidity - we specified the settings and enabled optimization
networks - networks, that we are going to use
gasReporter - will show us gas units, that we need to spend for deployment or calling the functions
etherscan - plugin for integration with Etherscan's contract verification service

The next step is to create .env file in project root. You have to create 5 variables:

PRIVATE_KEY - the private key of the wallet, that wil be the owner of the contract
ETHERSCAN_API_KEY - etherscan key. Register on https://etherscan.io and on the page https://etherscan.io/myapikey create and copy your key:

REPORT_GAS=1 - Are we going to use gas reporter or not. We will use it
GOERLI_URL and MAINNET_URL - use https://infura.io/ or https://www.alchemy.com/ for getting the urls.

For instance, infura URL for MAINNET_URL:

Infura URL for GOERLI_URL:

Now compile the code with the command:

npx hardhat compile

After that command some new folders will appear: artifacts, cache, typechain-types.

Step 3. Create deploy function

It's time to write deploy function, we will use tasks for it.

Remove folder scripts, we don't need it.

Create the folder tasks and the file deploy.ts inside it:

import { task } from "hardhat/config";

task("deploy").setAction(async function (_, { ethers, run }) {
  console.log("Start deploying");
  try {
    // The path to token metadata
    const baseUri = "https://my-domain.com/collection/metadata/";
    const _name = "My ERC721 name";
    const _symbol = "MyERC721Symbol";
    const ERC721Contract = await ethers.getContractFactory("ERC721Contract");
    const erc721Contract = await ERC721Contract.deploy(baseUri, _name, _symbol);

    await erc721Contract.deployed();

    console.log("Contract deployed to address:", erc721Contract.address);
  } catch (error) {
    console.error(error);
    process.exit(1);
  }
});

In this task we get smartcontract and deploy it. After the deployment in console we will see the address of the contract.

We will come back to that function later.

Step 4. Create tests

We will write the tests for every exteral/public function.

Clear the folder test and create index.ts inside it with the contents:

import { ethers } from "hardhat";
import { SignerWithAddress } from "@nomiclabs/hardhat-ethers/dist/src/signer-with-address";
import { ERC721Contract } from "../typechain-types";
import { expect } from "chai";

interface Signers {
  admin: SignerWithAddress;
  user: SignerWithAddress;
}

describe("ERC721Contract", function () {
  before(async function () {
    this.signers = {} as Signers;
    const signers: SignerWithAddress[] = await ethers.getSigners();
    this.signers.admin = signers[0];
    this.signers.user = signers[1];

    this.baseUri = "https://my-domain.com/collection/metadata/";
  });

  beforeEach(async function () {
    const _name = "My ERC721 name";
    const _symbol = "MyERC721Symbol";

    const ERC721ContractFactory = await ethers.getContractFactory(
      "ERC721Contract"
    );

    this.contract = <ERC721Contract>(
      await ERC721ContractFactory.deploy(this.baseUri, _name, _symbol)
    );

    await this.contract.deployed();
  });

  it("Mint 5 tokens by owner", async function () {
    await this.contract.mintByOwner(
      this.signers.user.address,
      "link_to_token_json1"
    );
    await this.contract.mintByOwner(
      this.signers.user.address,
      "link_to_token_json2"
    );
    await this.contract.mintByOwner(
      this.signers.user.address,
      "link_to_token_json3"
    );
    await this.contract.mintByOwner(
      this.signers.user.address,
      "link_to_token_json4"
    );
    await this.contract.mintByOwner(
      this.signers.user.address,
      "link_to_token_json5"
    );

    // Check balance of the user
    expect(await this.contract.balanceOf(this.signers.user.address)).to.equal(
      5
    );
  });

  it("Revert, if user is trying to use mintByOwner", async function () {
    expect(
      this.contract
        .connect(this.signers.user)
        .mintByOwner(this.signers.user.address, "link_to_token_json1")
    ).to.be.reverted;
  });

  it("Mint token by user", async function () {
    await this.contract
      .connect(this.signers.user)
      .mint({ value: ethers.utils.parseEther("0.1") });

    expect(await this.contract.balanceOf(this.signers.user.address)).to.equal(
      1
    );
  });

  it("Should revert INVALID_PRICE", async function () {
    expect(
      this.contract
        .connect(this.signers.user)
        .mint({ value: ethers.utils.parseEther("0.05") })
    ).to.be.revertedWith("INVALID_PRICE");
  });

  it("Should return back overpaid eth to sender", async function () {
    const price = ethers.utils.parseEther("0.1");
    expect(
      this.contract
        .connect(this.signers.user)
        .mint({ value: ethers.utils.parseEther("1.5") })
    ).to.changeEtherBalances(
      [this.signers.user, this.contract],
      [price.mul(-1), price]
    );
  });

  it("Check receiving eth to contract and withdraw", async function () {
    const value = ethers.utils.parseEther("1.5");
    await this.signers.user.sendTransaction({
      to: this.contract.address,
      value,
    });

    expect(this.contract.withdraw()).to.changeEtherBalances(
      [this.signers.admin, this.contract],
      [value, value.mul(-1)]
    );
  });

  it("Set base URI", async function () {
    const value = ethers.utils.parseEther("0.1");

    // Mint 2 tokens
    await this.contract.connect(this.signers.user).mint({ value });
    await this.contract.connect(this.signers.user).mint({ value });

    // Check token URI's
    expect(await this.contract.tokenURI(0)).to.be.equal(
      this.baseUri + "0.json"
    );
    expect(await this.contract.tokenURI(1)).to.be.equal(
      this.baseUri + "1.json"
    );

    // Change base URI
    const newBaseUri = "https://new_domain_or_ipfs/";
    await this.contract.setBaseURI(newBaseUri);

    // Check new token URI's
    expect(await this.contract.tokenURI(0)).to.be.equal(newBaseUri + "0.json");
    expect(await this.contract.tokenURI(1)).to.be.equal(newBaseUri + "1.json");
  });

  it("Check token URI", async function () {
    const value = ethers.utils.parseEther("0.1");

    // Mint token by user
    await this.contract.connect(this.signers.user).mint({ value });
    // Check token URI
    expect(await this.contract.tokenURI(0)).to.be.equal(
      this.baseUri + "0.json"
    );

    // Mint token by owner with specified URI
    await this.contract.mintByOwner(this.signers.user.address, "link_to_uri");

    // Check token URI
    expect(await this.contract.tokenURI(1)).to.be.equal(
      this.baseUri + "link_to_uri.json"
    );
  });
});

Run npx hardhat test.

You should get similar to that:

All tests passed successfully!

Step 5. Gas price for deployment and minting the smartcontract

For determine the price of deployment and minting functions we have used module hardhat-gas-reporter. It was enabled by default in hardhat.config.ts, that's why after all tests were passed, we got the table:

In the table we can see the gas consumption for methods and deployment.

This is the units of gas we need to deploy the contract.

How much it will cost in ETH?

Use the formula:

(gas units) * (gas price per unit) = gas fee in gwei

In this formula we don't know the amount of gas price per unit.

You can use https://ethgasstation.info/ or any other website to find this information. At the moment of writing this article, gas price is 17.

The value can change greatly depending on the time of day. It may be 2 or 10 or 50 🙃. Be careful.

So, the average cost will be:

Deployment = 1 697 092 * 17 = 28 850 564 gwei = 0,028850564 ETH
mint = 88 753 * 17 = 1 508 801 gwei = 0,001508801 ETH
mintByOwner = 91 060 * 17 = 1 548 020 gwei = 0,001548020 ETH
setBaseURI = 32 153 * 17 = 546 601 gwei = 0,000546601 ETH
withdraw = 30 421 * 17 = 517 157 gwei = 0,000517157 ETH

Now the ETH/USD price is $1 592, it means that deployment to mainnet will cost about $46 and calling a mint function will cost about $2.4.

Step 6. Creating images and metadata for NFT

Images and metadata for NFTs can be stored on your server or in IPFS.

We will cover the first case. Assume, that you have a domain

https://my-domain.com

All NFT images will store here:

https://my-domain.com/collection/assets/

All metadata here:

https://my-domain.com/collection/metadata/

So, the base URI for our smartcontract will be

https://my-domain.com/collection/metadata/

In our smartcontract by default all token URI's will be counted from 0. Therefore, files for metadata should be like this:

0.json
1.json
....
1234.json

If you will use mintByOwner function, then you can change the name of the file for specific NFT, and it can be like this: custom.json

Upload NFT images on your server. They should be available by links:

https://my-domain.com/collection/assets/0.png
https://my-domain.com/collection/assets/1.png
https://my-domain.com/collection/assets/2.png

Now create metadata for NFT's.

Here is an example of one file 0.json:

{
    "name": "Test NFT #0",
    "image": "https://my-domain.com/collection/assets/0.png"
}

Pay attention, that in image we have defined the link to the image, which has been uploaded to the server.

Read more about opensea metadata and available values in it.

Upload your metadata files, so they should be available by links:

https://my-domain.com/collection/metadata/0.json
https://my-domain.com/collection/metadata/1.json
https://my-domain.com/collection/metadata/2.json

Step 7. Deploy and verify smartcontract

Everything is ready for deployment.

Take a look on our tasks/deploy.ts, we've specified baseUri as

https://my-domain.com/collection/metadata/

This is because all our metadata is available by this address.

Here you can change the name and the symbol of the collection.

In command line run:

npx hardhat deploy --network goerli

This command will deploy smartcontract to Goerli network. If you want to deploy to mainnet, you can run:

npx hardhat deploy --network mainnet

All these networks were described on hardhat.config.ts file.

After the deployment you will get the following in your console:

My smartcontract address is:

0xc191B6505B16EBe5D776fb30EFbfe41A9252023a

From now, it is available on etherscan testnet:

https://goerli.etherscan.io/address/0xc191B6505B16EBe5D776fb30EFbfe41A9252023a

We need to verify our smartcontract, so everyone can check the code.

Wait about 5 minutes and try to verify it. If you get an error while verifying, don't worry, just try to wait more time. In Mainnet I was waiting for 10–15 minutes.

In general verify function looks like this:

npx hardhat verify --network <YOUR_NETWORK> <DEPLOYED_CONTRACT_ADDRESS> <arg1> <arg2> <argn>

Let's try to determine, what to specify in our verify function:

<YOUR_NETWORK> - goerli
<DEPLOYED_CONTRACT_ADDRESS> will be my contract address

0xc191B6505B16EBe5D776fb30EFbfe41A9252023a

<arg1> - this is our base URI. You will find it in tasks/deploy.ts

"https://my-domain.com/collection/metadata/"

<arg2> - name of the token collection, that was specified in deployment:

"My ERC721 name"

<arg3> - symbol of the token collection, that was specified in deployment:

"MyERC721Symbol"

Arguments should be the same, that were in tasks/deploy.ts!!!

So, in command line I will run:

npx hardhat verify --network goerli 0xc191B6505B16EBe5D776fb30EFbfe41A9252023a "https://my-domain.com/collection/metadata/" "My ERC721 name" "MyERC721Symbol"

The result should be the next:

On this page you can check the code of deployed smartcontract.

🥳We have finished with the smartcontract. Here is the repo, where you can find all the code.

Step 8. Create demo website for minting

This will be our second project erc721-mint.

For demo website I will use NextJS.

To speed up the development clone my repository: https://github.com/gapon2401/erc721-mint

Install all dependencies:

yarn install

Open file .env and fill in the variables:

NEXT_PUBLIC_SMARTCONTRACT_ADDRESS - address of your smartcontract from the paragraph Deploy and verify smartcontract.
NEXT_PUBLIC_SMARTCONTRACT_NETWORK - the network, where your smartcontract was deployed. We need this to switch the network. Specify goerli, because we have deployed our smartcontact there.
NEXT_PUBLIC_SMARTCONTRACT_INFURA_URL - network endpoint. You can use https://infura.io to get the url.

Go to your dashboard, select your project and copy Api Key:

In our first smartcontract project erc721 open the file:

artifacts/contracts/ERC721Contract.sol/ERC721Contract.json

Copy abi:

In current project erc721-mint open the file:

src/components/smartcontract.ts

Replace the abi value.

Everything is done! 🎉 You can run the project yarn dev and try to use it!

In the next section I will cover the main components.

Step 9 (optional). Deep dive and customize

Take a look on main components:

1) src/components/smartcontract.ts

Contains information about the smartcontract. It's better to dynamically load this file from the server, because we want our web page loads as soon as possible. In this demo mint form appears after the page loads.

2) src/components/Web3Provider.tsx

This component communicates with blockchain. There are some functions and variables stored in React Context:

connected - has user connected the wallet or not
isConnecting- the state of reconnecting
connect() - function for connecting to network
reconnect() – function for reconnecting. Cached provider will be used, that was selected by user at the last time
disconnect() – function for disconnecting
network – selected by user network: goerli, mainnet etc
provider – provider for communicating with the wallet: metamask, ledger, tokenary, etc
signer- the owner of the wallet
chainId – ID of the selected network
accountId – your wallet address
error - error message for web3Modal

3) src/components/MintForm.tsx

This component displays form for minting.

Function mint() is called after the user clicks on the mint button.

Now look at the code:

const transactionResponse = await Contract.mint({
    value: ethers.utils.parseEther('0.1'),
})

We are calling mint function from the smartcontract and send 0.1 ETH to it, because this function requires exactly that value.

What if we want to call mintByOwner?

We can do it like this:

const transactionResponse = await Contract.mintByOwner(
    '0x01234566', 'token_uri'
)

But pay attention, that this function can be called only by the owner of the contract. Why? We have used onlyOwner modifier in smartcontract:

function mintByOwner(address to, string calldata tokenUri) external onlyOwner

A few more words about that function.

0x01234566 - this is the address, for which you want to mint token. Make sure to write full address.

token_uri - this is custom token URI. In our deployed smartcontract the full address to token metadata looks like:

${baseUri + token_uri}.json

Remember, we have specified baseUri:

https://my-domain.com/collection/metadata/

So, the full address to metadata with token URI equals token_url will be:

https://my-domain.com/collection/metadata/token_url.json

Also, we don't need to pay for this transaction, except gas price.

Function prepareNetwork().

On first connection this function can propose to change the network. In this function are used only goerli and mainnet networks. You can change it, if you need, here:

chainId: smartContract.network === 'goerli' ? '0x5' : '0x1',

Function getBalanceOf.

This function checks is it enough money on the wallet to make a transaction.

In the file you may find commented code in two places:

/* reconnect ,*/

and

/* Reconnect to the wallet */
// useEffect(() => {
//   ;(async () => {
//     await reconnect()
//   })()
// }, [reconnect])

Uncomment it to make reconnections every time the page reloads.

Thank you for reading! ❤

NextJS. Use notFound in getStaticProps and some dynamic data? Don’t forget to revalidate!

Igor — Mon, 04 Jul 2022 10:00:26 +0000

If you have static pages in NextJS and some dynamic data decides whether to return “notFound” or not, always use “revalidate” in return statement.

I will show you what I mean, because such case is not excluded at all.

We are going to use NextJs и Express.

Creating NextJS project

Let’s create NextJs application by running:

yarn create next-app --typescript

After the installation is complete, run yarn dev to start the development server on http://localhost:3000.

If you open the page, you will see something similar to the following:

Inside pages create file [url].tsx with the contents:

export const getStaticPaths = async () => {
    return {
        paths: [
            {
                params: {
                    url: 'test',
                }
            },
        ],
        fallback: 'blocking',
    }
}

export const getStaticProps = async () => {

    // Request to api
    const response = await fetch('http://localhost:3001')
    const body = await response.json()

    // If page not exists return "Not found"
    if (!body.status) {
        return {
            // This can be a problem without revalidate
            notFound: true
        }
    }

    return {
        props: {
            response: body,
        },
        revalidate: 10,
    }
}

export default function Url() {
    return (
        <p>Hello world</p>
    )
}

This is the crucial moment:

// If page not exists return "Not found"
if (!body.status) {
    return {
        // This can be a problem without revalidate
        notFound: true,
    }
}

If on the build stage your page returns notFound, it will always be not found, even if body.status will be true in the future

Let’s check it and run test server using Express.

Create project for Express server

Create new project and install Express.

In command line run:

yarn add -D express @types/express nodemon ts-node typescript

Add to package.json:

"main": "index.ts",
"scripts": {
  "start": "nodemon index.ts"
},

In order to get the following:

{
  "main": "index.ts",
  "scripts": {
    "start": "nodemon index.ts"
  },
  "devDependencies": {
    "@types/express": "^4.17.13",
    "express": "^4.18.1",
    "nodemon": "^2.0.18",
    "ts-node": "^10.8.1",
    "typescript": "^4.7.4"
  }
}

In the root of that project create file index.ts:

import express from 'express'

const app = express()
const port = 3001
app.get('/', (req, res) => {
    res.send({ status: false })
})

app.listen(port, () => {
    console.log(`⚡️[server]: listening on port ${port}`)
})

Pay attention, that we are returning false status for the page:

res.send({ status: false })

Now run the server:

yarn start

Reproduce the error and fix it

Let’s get back to NextJS project, run in the terminal:

yarn build

Then run NextJS server:

yarn start

Open the page http://localhost:3000/test and you will get 404 page. Try to refresh the page and you still get 404 error. This is because, when page was built, it got the status: false from our server in this line:

const response = await fetch('http://localhost:3001')

Consider, that now server returns true.

Go to the Server project and change the status:

res.send({ status: true })

Make sure that server was rebooted.

For NextJS project we are not doing rebuild, just checking the page http://localhost:3000/test. Nothing changes. Wait a bit, make one more refresh. Still got 404.

To fix such behaviour add revalidate: 5 in file [url].tsx:

if (!body.status) {
    return {
        notFound: true,
        // We use 5 only for demonstration purpose
        revalidate: 5
    }
}

Now, you will have a page rebuild, if it was not available and then the status was changed to available. It is called incremental static regeneration.

I’ll describe how to check that everything was fixed.

In Server project return back:

res.send({ status: false })

Make sure that server was rebooted.

In NextJS project run commands yarn build and yarn start.

Go to the page http://localhost:3000/test and make sure that it returns 404 page.

In Server project set status true:

res.send({ status: true })

Make sure that server was rebooted. Return back to the page [http://localhost:3000/test](http://localhost:3000/test, refresh, it will be 404 page. Wait for 5 seconds, NextJs triggers a regeneration. Now, if you reload the page, it should be available.

This is it! Thank you for reading.

How to create and publish React Typescript npm package with demo and automated build

Igor — Thu, 30 Jun 2022 09:12:27 +0000

In this article I will show you how to create React module on Typescript, create demo page, description for it and publish as node package. We will use Eslint, Jest, Prettier, github pages for demo-page and github-actions to setup automated builds in releases.

Introduction

Why did I decide to write one more article about publishing npm-packages? When I needed to create such a package by myself, I found that most of the instructions on the Internet were either outdated or very short and useless in production.

I will try to describe all the steps as clear as I can, so you can create your own project from the scratch. Let’s get started!

I propose to create a simple react application, which will consist of two buttons that increase or decrease the value of the counter.

This is how our application will look like:

Demo: https://gapon2401.github.io/my-react-typescript-package

Repo: https://github.com/gapon2401/my-react-typescript-package

We have 14 steps to deal with everything:

Preparing the project
Create your react application
Configure git
Configure ESLint
Configure Prettier
Adding tests with Jest
Configure package.json and prepare for publishing
Commit and push your code
Publishing to NPM
Creating of the example folder
Setup automated builds
Demo page
README.md file and shields.io
Making release

Step 1. Preparing the project

In command line of your project execute:

npm init -y

It will create package.json file with default values, we will change it a bit later.

Create folder src

Here we will keep all project files.

Add React and Typescript to the project (I’m going to use yarn, if you don’t mind)

yarn add -D react react-dom typescript @types/react

Now we have node_modules folder and a yarn.lock — not bad!

In order to compile typescript, create a tsconfig.json file in the project root with the contents

{
  "include": ["src"],
  "exclude": [
    "dist",
    "node_modules"
  ],
  "compilerOptions": {
    "module": "esnext",
    "lib": ["dom", "esnext"],
    "importHelpers": true,
    "declaration": true,
    "sourceMap": true,
    "rootDir": "./src",
    "outDir": "./dist/esm",
    "strict": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "moduleResolution": "node",
    "jsx": "react",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
  }
}

You can take a look at all possible properties here: https://www.typescriptlang.org/tsconfig

From the main:

-- rootDir — the root folder within your source files,

-- include — specifies the files to be included in the TypeScript project,

-- exclude — specifies the files to be excluded in the TypeScript project. We don’t want to include dist folder and all node_modules ,

-- outDir — this is the location for the compiled output

Create empty README.md and LICENSE files.

It’s up to you what license to use. I will use MIT, you can check the contents of that file.

Take a look at the structure we should have:

Step 2. Create your react application

Inside src create the folder components. There you can keep all the components of your project. We will create here within this article only one file App.tsx with the contents:

import React, { useState } from 'react'

type Props = {
    value?: number
}
const MyCounter = ({ value = 0 }: Props) => {
    const [counter, setCounter] = useState(value);

    const onMinus = () => {
        setCounter((prev) => prev - 1)
    };

    const onPlus = () => {
        setCounter((prev) => prev + 1)
    };

    return (
        <div>
            <h1>Counter: {counter}</h1>
            <button onClick={onMinus}>-</button>
            <button onClick={onPlus}>+</button>
        </div>
    )
}

export default MyCounter

This is our React application.

Now create file index.ts inside src folder. Export our module.

import MyCounter from './components/App'

export { MyCounter }

It’s time to compile the project! 🤗

Let’s change our package.json and replace scripts section:

{
  "name": "my-react-typescript-package",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "tsc"
  },
  "keywords": [],
  "author": "gapon2401",
  "license": "ISC",
  "devDependencies": {
    "@types/react": "^18.0.12",
    "react": "^18.1.0",
    "react-dom": "^18.1.0",
    "typescript": "^4.7.3"
  }
}

Run in terminal:

yarn build

Folder dist should be appeared with all compiled code.

Congratulations! 🎉 We have created the application, which is compiled, a few more steps and we’re done! (no..)

Compare your project structure after step 2:

Step 3. Configure git

We quickly have created the project, now it’s time for the git.

Initialize git in the root of the project

git init

Create file .gitignore in project root with contents:

node_modules
.idea
dist
yarn-error.log

I added .idea, because I’m developing with the help of Jetbrains IDE.

In .gitignore we list those files, directories that we would like not to include in the repository.

Create git repo on github. Later we will create initial commit and connect remote git with our local git.

Step 4. Configure ESLint

ESLint statically analyzes your code to quickly find problems. We need it only in development.

Add eslint and all necessary components:

yarn add -D eslint eslint-plugin-react eslint-plugin-react-hooks @typescript-eslint/eslint-plugin @typescript-eslint/parser

You can configure it as you want, there is a big user guide: https://eslint.org/docs/user-guide/configuring/

I suggest you create an .eslintrc file at the root of the project:

{
  "root": true,
  "extends": [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:@typescript-eslint/eslint-recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "parser": "@typescript-eslint/parser",
  "plugins": [
    "@typescript-eslint",
    "react",
    "react-hooks"
  ],
  "rules": {
    "react-hooks/rules-of-hooks": "error",
    "react-hooks/exhaustive-deps": "warn",
    "@typescript-eslint/no-non-null-assertion": "off",
    "@typescript-eslint/ban-ts-comment": "off",
    "@typescript-eslint/no-explicit-any": "off"
  },
  "settings": {
    "react": {
      "version": "detect"
    }
  },
  "env": {
    "browser": true,
    "node": true
  },
  "globals": {
    "JSX": true
  }
}

Add .eslintignore:

node_modules
dist

We will ignore checking dist folder with compiled files and node_modules.

Change package.json, add to scripts section:

"lint": "eslint \"{**/*,*}.{js,ts,jsx,tsx}\""

Here is my package.json:

{
  "name": "my-react-typescript-package",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "tsc",
    "lint": "eslint \"{**/*,*}.{js,ts,jsx,tsx}\""
  },
  "keywords": [],
  "author": "gapon2401",
  "license": "ISC",
  "devDependencies": {
    "@types/react": "^18.0.12",
    "@typescript-eslint/eslint-plugin": "^5.27.1",
    "@typescript-eslint/parser": "^5.27.1",
    "eslint": "^8.17.0",
    "eslint-plugin-react": "^7.30.0",
    "eslint-plugin-react-hooks": "^4.5.0",
    "react": "^18.1.0",
    "react-dom": "^18.1.0",
    "typescript": "^4.7.3"
  }
}

Now, run:

yarn lint

You shouldn’t have any mistakes.

Compare your project structure after step 4:

Step 5. Configure Prettier

Prettier is a code formatter. It is convenient to use it when you work in a team so that everyone’s code meets the same standard.

In terminal run the command:

yarn add -D eslint-config-prettier eslint-plugin-prettier prettier

In project root create .prettierrc.json:

{
  "bracketSpacing": true,
  "singleQuote": true,
  "trailingComma": "all",
  "tabWidth": 2,
  "semi": false,
  "printWidth": 120,
  "jsxSingleQuote": true,
  "endOfLine": "auto"
}

Read more about all options: https://prettier.io/docs/en/options.html.

Add prettier plugin to .eslintrc:

{
  "root": true,
  "extends": [
    "prettier",
    "plugin:prettier/recommended",
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:@typescript-eslint/eslint-recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "parser": "@typescript-eslint/parser",
  "plugins": [
    "@typescript-eslint",
    "prettier",
    "react",
    "react-hooks"
  ],
  "rules": {
    "react-hooks/rules-of-hooks": "error",
    "react-hooks/exhaustive-deps": "warn",
    "@typescript-eslint/no-non-null-assertion": "off",
    "@typescript-eslint/ban-ts-comment": "off",
    "@typescript-eslint/no-explicit-any": "off"
  },
  "settings": {
    "react": {
      "version": "detect"
    }
  },
  "env": {
    "browser": true,
    "node": true
  },
  "globals": {
    "JSX": true
  }
}

We have finished the setup of prettier, now try to run yarn lint in order to check formatting errors. If you don’t have any, so you didn’t pass the human test 😆

It’s time to fix them! Add to scripts in package.json:

"prettier": "prettier --write \"{src,tests,example/src}/**/*.{js,ts,jsx,tsx}\""

Ok, run yarn prettier and you will get something similar to:

Now after yarn lint you should not have any errors. Check the files src/components/App.tsx and src/index.ts, they have changed.

My scripts section in package.json:

"scripts": {
  "build": "tsc",
  "lint": "eslint \"{**/*,*}.{js,ts,jsx,tsx}\"",
  "prettier": "prettier --write \"{src,tests,example/src}/**/*.{js,ts,jsx,tsx}\""
}

Compare your project structure after step 5:

Step 6. Adding tests with Jest

For creating tests I’m using Jest library. It’s pretty useful and powerful testing framework. How difficult the tests will be, of course, is up to you.

Add jest to your project:

yarn add -D jest jest-canvas-mock jest-environment-jsdom ts-jest @types/jest @testing-library/react

Create at the project root file jestconfig.json:

{
  "transform": {
    "^.+\\.(t|j)sx?$": "ts-jest"
  },
  "testRegex": "(/tests/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$",
  "moduleFileExtensions": ["ts", "tsx", "js", "jsx", "json", "node"],
  "testEnvironment": "jsdom"
}

Create folder tests.

Time to write our first test. We will write very simple test, which will check, that our render passed successful.

In folder tests create file common.test.tsx:

import * as React from 'react'
import { render } from '@testing-library/react'

import 'jest-canvas-mock'

import { MyCounter } from '../src'

describe('Common render', () => {
  it('renders without crashing', () => {
    render(<MyCounter />)
  })
})

Change scripts section in package.json:

"test": "jest --config jestconfig.json"

{
  "name": "my-react-typescript-package",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "tsc",
    "lint": "eslint \"{**/*,*}.{js,ts,jsx,tsx}\"",
    "prettier": "prettier --write \"{src,tests,example/src}/**/*.{js,ts,jsx,tsx}\"",
    "test": "jest --config jestconfig.json"
  },
  "keywords": [],
  "author": "gapon2401",
  "license": "ISC",
  "devDependencies": {
    "@testing-library/react": "^13.3.0",
    "@types/jest": "^28.1.1",
    "@types/react": "^18.0.12",
    "@typescript-eslint/eslint-plugin": "^5.27.1",
    "@typescript-eslint/parser": "^5.27.1",
    "eslint": "^8.17.0",
    "eslint-config-prettier": "^8.5.0",
    "eslint-plugin-prettier": "^4.0.0",
    "eslint-plugin-react": "^7.30.0",
    "eslint-plugin-react-hooks": "^4.5.0",
    "jest": "^28.1.1",
    "jest-canvas-mock": "^2.4.0",
    "jest-environment-jsdom": "^28.1.1",
    "prettier": "^2.6.2",
    "react": "^18.1.0",
    "react-dom": "^18.1.0",
    "ts-jest": "^28.0.4",
    "typescript": "^4.7.3"
  }
}

Run yarn test. You should pass the test:

Compare your project structure after step 6:

Step 7. Configure package.json and prepare for publishing

I suggest to split our build. We will compile not only the ECMAScript module, but also the CommonJs module to make our package as accessible as possible.

In package.json replace:

"build": "tsc",

With the following code:

"build": "yarn build:esm && yarn build:cjs",
"build:esm": "tsc",
"build:cjs": "tsc --module commonjs --outDir dist/cjs",

We added build:esm and build:cjs and combined them in one command.

Run yarn build and you will see, that our dist/ now has also a cjs folder.

Go further.

In package.json we can use magic scripts that are automatically called when the package is published. They will help us to check our package for all kinds of errors and not accidentally upload an update that will crash hundreds of thousands of projects in which our package will be used! 😜

prepare — runs BEFORE the package is packed and published. Runs on local npm install without any arguments,
prepublishOnly — runs BEFORE the package is prepared and packed, ONLY on npm publish. Here will be our tests.

Add to scripts section:

"prepare": "npm run build",
"prepublishOnly": "npm test && npm run prettier && npm run lint"

Change the version, description.

Tell npm where it can import the main file of our project from, and also where all the types are located:

Replace:

"main": "index.js",

With:

"main": "./dist/cjs/index.js",
"module": "./dist/esm/index.js",
"types": "./dist/esm/index.d.ts",

Add information about remote git repository (specify your git url from step 3):

"repository": {
  "type": "git",
  "url": "git+https://github.com/gapon2401/my-react-typescript-package.git"
},

Specify that the project that will use our package must have a react version of at least >=16:

"peerDependencies": {
  "react": ">=16"
},

To ensure that your package does not have any redundant files, use only allowed files and folders that will be added to the package:

"files": [
  "dist",
  "LICENSE",
  "README.md"
],

Add keywords so everyone can find your project:

"keywords": [
  "react",
  "typescript",
  "awesome-project"
],

Specify your license:

"license": "MIT",

Don’t forget to change the author:

"author": "Igor Gaponov (gapon2401)",

I think that’s enough.)

Add description to your README.md file.

For now I have only one row there. This is the h1:

# my-react-typescript-package

Take a look at the final version of package.json:

{
  "name": "my-react-typescript-package",
  "version": "0.1.0",
  "description": "My first react typescript package",
  "main": "./dist/cjs/index.js",
  "module": "./dist/esm/index.js",
  "types": "./dist/esm/index.d.ts",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/gapon2401/my-react-typescript-package.git"
  },
  "scripts": {
    "build": "yarn build:esm && yarn build:cjs",
    "build:esm": "tsc",
    "build:cjs": "tsc --module commonjs --outDir dist/cjs",
    "lint": "eslint \"{**/*,*}.{js,ts,jsx,tsx}\"",
    "prettier": "prettier --write \"{src,tests,example/src}/**/*.{js,ts,jsx,tsx}\"",
    "test": "jest --config jestconfig.json",
    "prepare": "npm run build",
    "prepublishOnly": "npm test && npm run prettier && npm run lint"
  },
  "peerDependencies": {
    "react": ">=16"
  },
  "files": [
    "dist",
    "LICENSE",
    "README.md"
  ],
  "keywords": [
    "react",
    "typescript",
    "awesome-project"
  ],
  "author": "Igor Gaponov (gapon2401)",
  "license": "MIT",
  "devDependencies": {
    "@testing-library/react": "^13.3.0",
    "@types/jest": "^28.1.1",
    "@types/react": "^18.0.12",
    "@typescript-eslint/eslint-plugin": "^5.27.1",
    "@typescript-eslint/parser": "^5.27.1",
    "eslint": "^8.17.0",
    "eslint-config-prettier": "^8.5.0",
    "eslint-plugin-prettier": "^4.0.0",
    "eslint-plugin-react": "^7.30.0",
    "eslint-plugin-react-hooks": "^4.5.0",
    "jest": "^28.1.1",
    "jest-canvas-mock": "^2.4.0",
    "jest-environment-jsdom": "^28.1.1",
    "prettier": "^2.6.2",
    "react": "^18.1.0",
    "react-dom": "^18.1.0",
    "ts-jest": "^28.0.4",
    "typescript": "^4.7.3"
  }
}

Step 8. Commit and push your code

First of all, let’s connect remote and local repositories and push our project.

Run the following code:

git add .
git commit -m "Initial commit"
git remote add origin <Repository Url>
git push -u origin master

Don’t forget to change <Repository Url> on yours. It can be https url, or ssh. This url you can get in your repository.

Take a look on examples, how it could be.

HTTPS repository url (you will need to authorize)

git remote add origin https://github.com/gapon2401/my-react-typescript-package.git

SSH repository url (you need to configure connecting with ssh)

git remote add origin git@github.com:gapon2401/my-react-typescript-package.git

I use the second solution.

Step 9. Publishing to NPM

Choose the package name

We have to check that the name of our package is free to use. Go to the website https://www.npmjs.com/ and use search tool.

You can find and change default name of the project in package.json:

In my case it my-react-typescript-package. There is no such package yet.

I prefer to check this way: insert the name directly to the link

https://www.npmjs.com/package/<Your package name>

Instead of <Your package name> use the name of your project.

I get the following url:

https://www.npmjs.com/package/my-react-typescript-package

If the name is free, you will see 404 page:

Register/login to NPM

In order to publish the project you need to authorize in https://www.npmjs.com/.

If you don’t have account yet, go and register https://www.npmjs.com/signup or use command line:

npm adduser

You will be asked to enter username, password and email.

If you already have an account, run:

npm login

And complete the authorization.

Publishing

Before publishing, I recommend you to check that you will have only the necessary files in the package, there are no errors, everything is formatted correctly. For this you can run the command:

npm publish --dry-run

Package WILL NOT BE published, don’t worry.

You will see, that the “magic script” prepublishOnly will be called and tests and code formatting will run.

Then you will get the list of all files, which will be included at the project:

In Tarball Contents we have the files and folders, that were specified in package.json:

"files": [
  "dist",
  "LICENSE",
  "README.md"
],

Everything is fine, let’s publish the package!

Run the command:

npm publish

I always worry, when run this command 🤣

I am attaching the full result of the command call:

Now I can congratulate you!🎉 The package is published, it is public, it can be used by anyone! It wasn’t so hard 😉

Let’s take a look at the package on the NPM.

Open the link, we did it before.

https://www.npmjs.com/package/<Your package name>

Looks great! 🔥

Step 10. Creating of the example folder

Let’s keep making our package better and better. In this step we will create an example folder in which we will show how we can work with our package. In this folder, you can quickly start the server, play around with the code.
To quickly launch the application, we will use https://parceljs.org/.

Create a folder example.

Inside that folder create empty folder src and files:

.gitignore:

node_modules
yarn.lock
.parcel-cache
dist
yarn-error.log

package.json:

{
  "name": "example",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "start": "parcel src/index.html"
  }
}

README.md:

# How to start example page?

Then in the example directory, run all dependencies:

### `yarn install`

Then use the command:

### `yarn start`

Open [http://localhost:1234](http://localhost:1234) to view it in the browser.

Now pay attention! In the command line from the root of your project move into example folder:

cd example

Then run:

yarn add -D parcel my-react-typescript-package react react-dom @types/react-dom @types/react

Inside src folder create the file index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta
      name="description"
      content="Example page for my-react-typescript-package"
    />
    <title>my-react-typescript-package</title>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <script type="module" src="index.tsx"></script>
    <div id="root"></div>
  </body>
</html>

Now we need to import our package and create the example of how to use it.

Inside src folder create index.tsx file:

import React from 'react'
import ReactDOM from 'react-dom/client'
import { MyCounter } from 'my-react-typescript-package'

const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement)
root.render(
  <React.StrictMode>
    <div>
      <h2>Default counter</h2>
      <MyCounter />
    </div>
    <hr />
    <div>
      <h2>Counter with predefined value</h2>
      <MyCounter value={5} />
    </div>
  </React.StrictMode>,
)

Time to run the server! Use the command:

yarn start

You will have the following message after successfully starting the server:

Open the link http://localhost:1234 to watch the example:

Compare the example folder structure, after all installations and server running, it should look like this:

Step 11. Setup automated builds

Let’s get into automated builds. It’s rather inconvenient when you have to push changes to git, to npm with each release. We will automate this process with Github Actions.

Create at the root of the project structure the folder .github.

Inside it create the folder workflows.

Inside workflows create the file publish.yml:

# This is a name of the workflow
name: build
# Controls when the workflow will run
on:
  # Triggers the workflow on published releases
  release:
    types: [published]
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest
    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:

      - name: Checkout
        # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
        uses: actions/checkout@v3

      - name: Setup Node
        # Setup node environment
        uses: actions/setup-node@v3
        with:
          # Node version. Run "node -v" to check the latest version
          node-version: 16.x
          registry-url: https://registry.npmjs.org/

      - name: Install dependencies
        run: yarn && yarn install

      - name: Build
        run: yarn build

      - name: Publish
        run: yarn publish

        env:
          # We need this to our NPM account
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

The main points in the file have been commented.

When we will release to github, our package will be automatically built and pushed to NPM.

I want you to look at the line:

# We need this to our NPM account
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

This is the way we are going to connect Github with NPM.

In browser open your account on https://www.npmjs.com/, go to the page with tokens:

Generate new token:

You will be prompted to enter its name and select the type. Automation is suitable for github-actions:

Copy your token and open the github repo.

Go to the tab Settings, open Secrets — Actions and create new repository secret variable. Give it a name NPM_TOKEN and paste inside the value of the token from NPM:

Well done! Now it remains to create a new version of the project and push it to github.

Don’t forget before committing any changes to run:

yarn prepublishOnly

Just to make sure that your code will be nice and clean.

After you push the project, go to the Actions tab, where you will see that github has detected that you have workflow actions. But it hasn’t launched anything yet, because we haven’t made a release yet.)

Step 12. Demo page

We have already a folder with an example of using our package, but we would like to create a separate page so that the user can quickly see the package in action without having to clone the entire project. Let’s get on with this page!

We will use github-pages for creating the demo.

Create new git branch:

git checkout -b gh-pages

And now delete all the files from the project! 😱

Don’t worry, all previous files will stay safe in another master branch. The branch gh-pages will be used only for the demo, that’s why we need to delete all files. Come on, delete everything! 😈

Then in command line run:

npm init -y

This command will create file package.json. We will not configure it in detail this time.

For demo page I suggest using parcel, which is familiar for us (step 10)

Run:

yarn add -D parcel my-react-typescript-package react react-dom @types/react-dom @types/react typescript

Create file .gitignore:

node_modules
yarn.lock
.parcel-cache
dist
yarn-error.log

Create file tsconfig.json with contents:

{
  "include": ["src"],
  "exclude": [
    "dist",
    "node_modules"
  ],
  "compilerOptions": {
    "module": "esnext",
    "lib": ["dom", "esnext"],
    "importHelpers": true,
    "declaration": true,
    "sourceMap": true,
    "rootDir": "./src",
    "outDir": "./dist/esm",
    "strict": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "moduleResolution": "node",
    "jsx": "react",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
  }
}

Follow the step 4 to configure the Eslint.

Create empty folder src. Inside it create file index.html with the contents:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta
        name="description"
        content="Demo page for my-react-typescript-package"
    />
    <title>Demo page of my-react-typescript-package</title>
</head>
<body>
<noscript>You need to enable JavaScript to run this app.</noscript>
<script type="module" src="./index.tsx"></script>
<div id="root"></div>
</body>
</html>

Create file index.tsx:

Add to package.json inside scripts section:

"start": "parcel src/index.html",
"build": "parcel build src/index.html --dist-dir docs --public-url .",

Take a look at my package.json:

{
  "name": "my-react-typescript-package",
  "version": "0.1.0",
  "description": "Demo page of my-react-typescript-package",
  "scripts": {
    "start": "parcel src/index.html",
    "build": "parcel build src/index.html --dist-dir docs --public-url .",
    "lint": "eslint \"{**/*,*}.{js,ts,jsx,tsx}\""
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/gapon2401/my-react-typescript-package.git"
  },
  "author": "gapon2401",
  "license": "MIT",
  "devDependencies": {
    "@types/react": "^18.0.14",
    "@types/react-dom": "^18.0.5",
    "@typescript-eslint/eslint-plugin": "^5.29.0",
    "@typescript-eslint/parser": "^5.29.0",
    "eslint": "^8.18.0",
    "eslint-plugin-react": "^7.30.0",
    "eslint-plugin-react-hooks": "^4.6.0",
    "my-react-typescript-package": "^0.1.0",
    "parcel": "^2.6.2",
    "process": "^0.11.10",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "typescript": "^4.7.4"
  }
}

Run the server to make sure, that everything works fine:

yarn start

Now run the code checking:

yarn lint

No errors! 🤗 Great! It’s time to build the page.

yarn build

You should see the folder docs with all files of the demo project.

Here is the structure of the branch gh-pages:

Now let’s push all the changes to git. Run:

git add .
git commit -m "Initial pages commit"
git push -u origin gh-pages

Open your github repository and go to Settings — Pages. In the source select /docs and press Save:

Wait about 3–5 minutes and your site will be available on the specified url, which is on your page:

We have done with the demo page. As you see, you can customize it however you want and create a page or website of any complexity.

Here is the result: https://gapon2401.github.io/my-react-typescript-package/

Step 13. README.md file and shields.io

Now when we’ve done with all the code, we can move to the description file of the package.

Switch to master branch in git and open README.md.

Replace contents with the following code:

For description file we are using markdown.

In README.md I have added a short description of the package, link to demo-page and a usage section.

At the beginning of the readme file I have small cute icons, this is https://shields.io/. It is very convenient to have them. I’ve added just a couple as an example, you can use as many as you want.

Add shields.io to your github applications.

Take a look at the end of the file, I’ve created variables with images and links. Markdown allows us to make such variables, so the description file looks more accurate. Don’t forget to change the path to your repo and the package name.

Change version in package.json, make commit and push files to repository. Do everything by yourself, we’ve made it in previous steps.😉

Step 14. Making release

This is the last step. It will be short 🙌

We have done everything, what we planned! Now we can make an official release on github and also check how automated builds work.

Go to the main page of the repository and click Create a new release:

Specify your current version as a tag, it will be created automatically on release. Print release title and description and click Publish release.

Now open tab Actions and make sure, that your build was successfully done.

Let’s check, that package was updated in NPM.

Open the package link:

https://www.npmjs.com/package/<Your package name>

I will open mine:

https://www.npmjs.com/package/my-react-typescript-package

You should see a new version with new description:

Congratulations! 🥳🎉👏 You are brilliant! 💎✨

It was a long journey, but I hope very useful. I tried to describe everything that I had difficulty with when I first published my package and collected this information piece by piece.

Thank you for reading! ❤️

Upload files with NextJS + Fetch + Api routes + Typescript

Igor — Wed, 18 May 2022 16:07:21 +0000

You will learn, how to upload files using React, NextJs and Fetch API.

First of all, let’s create NextJs application by running:



yarn create next-app --typescript

After the installation is complete, run yarn dev to start the development server on http://localhost:3000 .

If you open the page, you will see something similar to the following:

Now let's install the packages, which will help us to parse form data:



yarn add -D formidable @types/formidable

Creating the form

We will create small form, where we can upload files. I will simplify the code to make it more clear.

Go to pages/index.js and replace all the default code with the following:



import type { NextPage } from 'next'
import React from "react";

const Home: NextPage = () => {

    const [isLoading, setIsLoading] = React.useState(false);
    const inputFileRef = React.useRef<HTMLInputElement | null>(null);

    const handleOnClick = async (e: React.MouseEvent<HTMLInputElement>) => {

        /* Prevent form from submitting by default */
        e.preventDefault();

        /* If file is not selected, then show alert message */
        if (!inputFileRef.current?.files?.length) {
            alert('Please, select file you want to upload');
            return;
        }

        setIsLoading(true);

        /* Add files to FormData */
        const formData = new FormData();
        Object.values(inputFileRef.current.files).forEach(file => {
            formData.append('file', file);
        })

        /* Send request to our api route */
        const response = await fetch('/api/upload', {
            method: 'POST',
            body: formData
        });

        const body = await response.json() as { status: 'ok' | 'fail', message: string };

        alert(body.message);

        if (body.status === 'ok') {
            inputFileRef.current.value = '';
            // Do some stuff on successfully upload
        } else {
            // Do some stuff on error
        }

        setIsLoading(false);
    };

    return (
        <form>
            <div>
                <input type="file" name="myfile" ref={inputFileRef} multiple />
            </div>
            <div>
                <input type="submit" value="Upload" disabled={isLoading} onClick={handleOnClick} />
                {isLoading && ` Wait, please...`}
            </div>
        </form>
    )
}

export default Home

Here we are using multiple files uploading. If you want to upload only one file, remove multiple from input:file:



<input type="file" name="myfile" ref={inputFileRef} />

API Route

Let’s create an endpoint, where we will process the uploaded files.

Create the filepages/api/upload.ts:



import type { NextApiRequest, NextApiResponse } from 'next'
import { promises as fs } from "fs";
import path from "path";
import formidable, { File } from 'formidable';

/* Don't miss that! */
export const config = {
    api: {
        bodyParser: false,
    }
};

type ProcessedFiles = Array<[string, File]>;

const handler = async (req: NextApiRequest, res: NextApiResponse) => {

    let status = 200,
        resultBody = { status: 'ok', message: 'Files were uploaded successfully' };

    /* Get files using formidable */
    const files = await new Promise<ProcessedFiles | undefined>((resolve, reject) => {
        const form = new formidable.IncomingForm();
        const files: ProcessedFiles = [];
        form.on('file', function (field, file) {
            files.push([field, file]);
        })
        form.on('end', () => resolve(files));
        form.on('error', err => reject(err));
        form.parse(req, () => {
            //
        });
    }).catch(e => {
        console.log(e);
        status = 500;
        resultBody = {
            status: 'fail', message: 'Upload error'
        }
    });

    if (files?.length) {

        /* Create directory for uploads */
        const targetPath = path.join(process.cwd(), `/uploads/`);
        try {
            await fs.access(targetPath);
        } catch (e) {
            await fs.mkdir(targetPath);
        }

        /* Move uploaded files to directory */
        for (const file of files) {
            const tempPath = file[1].filepath;
            await fs.rename(tempPath, targetPath + file[1].originalFilename);
        }
    }

    res.status(status).json(resultBody);
}

export default handler;

Congratulations, we’re done! You can test your form!

All files will be saved in directory /uploads inside your project root.

Use Api route as proxy

Here I suggest you to assume, that we need to transfer our files somewhere else to another server, because we don’t want to store them and doing difficult operations on files.

Add some new packages:



yarn add -D form-data node-fetch

Change you /pages/api/upload.ts to:



import type { NextApiRequest, NextApiResponse } from 'next'
import fs from "fs";
import fetch from "node-fetch";
import FormData from 'form-data';
import formidable, { File } from 'formidable';

export const config = {
    api: {
        bodyParser: false,
    }
};

type ProcessedFiles = Array<[string, File]>;

const handler = async (req: NextApiRequest, res: NextApiResponse) => {

    let status = 200,
        resultBody = { status: 'ok', message: 'Files were uploaded successfully' };

    /* Get files using formidable */
    const files = await new Promise<ProcessedFiles | undefined>((resolve, reject) => {
        const form = new formidable.IncomingForm();
        const files: ProcessedFiles = [];
        form.on('file', function (field, file) {
            files.push([field, file]);
        })
        form.on('end', () => resolve(files));
        form.on('error', err => reject(err));
        form.parse(req, () => {
            //
        });
    }).catch(e => {
        console.log(e);
        status = 500;
        resultBody = {
            status: 'fail', message: 'Upload error'
        }
    });

    if (files?.length) {

        /* Add files to FormData */
        const formData = new FormData();
        for (const file of files) {
            formData.append(file[0], fs.createReadStream(file[1].filepath));
        }

        /* Send request to another server */
        const response = await fetch('PATH_TO_ANOTHER_SERVER', {
            headers: formData.getHeaders(),
            method: 'POST',
            body: formData
        });

        // Do anything you need with response

    }

    res.status(status).json(resultBody);
}

export default handler;

Don’t forget to replace PATH_TO_ANOTHER_SERVER.

This is it, enjoy! Full repo https://github.com/gapon2401/upload-files-nextjs

Add colorpicker to Ant Design form

Igor — Wed, 18 May 2022 06:48:16 +0000

This is an overview for the npm package antd-colorpicker

Ant design is very convinient design system for building efficient user interfaces.

While working with it, I faced with the necessity of adding colorpicker to my form. Unfortunately, there is no such component.
Antd docs suggest to use third-party libraries for creating the colorpicker.

Eventually, I decided, that it will be helpful to write npm package for everyone, who will faced with the same issue as I am.

NPM antd-colorpicker

How to use it?

Install the package:

npm install antd-colorpicker --save-dev

yarn add -D antd-colorpicker

Add Colorpicker to your form inside Form.Item:

import React from 'react'
import { Button, Form } from 'antd'
import { Colorpicker, ColorPickerValue } from 'antd-colorpicker'

import 'antd/dist/antd.css'

const App = () => {
  const initialValues = { color: { r: 26, g: 14, b: 85, a: 1 } }
  const handleOnFinish = (values: { color: ColorPickerValue }) => {
    console.log(values)
  }

  return (
    <Form onFinish={handleOnFinish} initialValues={initialValues}>
      <Form.Item label={'Colorpicker'} name={`color`}>
        <Colorpicker />
      </Form.Item>
      <Form.Item>
        <Button type='primary' htmlType='submit'>
          Show values in console
        </Button>
      </Form.Item>
    </Form>
  )
}

export default App

It will be the simpliest colorpicker.

Customization

You can use the following properties to customize the colorpicker:

Property	Description	Type	Default
picker	Type of the picker	BlockPicker ChromePicker CirclePicker CompactPicker GithubPicker GooglePicker HuePicker MaterialPicker PhotoshopPicker SketchPicker SliderPicker SwatchesPicker TwitterPicker	SketchPicker
popup	Use popup for colorpicker. Component Popover	boolean	false
onColorResult	Function that changes the color value, which will be returned	function(color)	undefined
blockStyles	Relevant only when `popup=true`. CSS styles for block, which changes the color after picking it at popup window	CSSProperties	{ }
popoverProps	Properties for `Popover` component	object	{ }
...rest	Custom properties for react-color pickers	props

Examples

Popup window

<Colorpicker popup />

Change block, which fires popup window

<Colorpicker
  popup
  blockStyles={{
    width: '30px',
    height: '30px',
    borderRadius: '50%',
  }}
/>

Choose one of the 13 types of picker

<Colorpicker picker={'CirclePicker'} />

Customize the result value of the color

By default you will have the following color result:

{
  "hsl": {
    "h": 250.3448275862069,
    "s": 0.1594202898550725,
    "l": 0.346725,
    "a": 1
  },
  "hex": "#4f4a67",
  "rgb": {
    "r": 79,
    "g": 74,
    "b": 103,
    "a": 1
  },
  "hsv": {
    "h": 250.3448275862069,
    "s": 0.2750000000000001,
    "v": 0.402,
    "a": 1
  },
  "oldHue": 250.3448275862069,
  "source": "hsv"
}

Let's try to change it, to get what we want:

<Colorpicker onColorResult={(color) => color.rgb} />

The result value will be:

{
  "r": 79,
  "g": 74,
  "b": 103,
  "a": 1
}

How to use the component outside the form?

You have to define value and onChange (or onChangeComplete) props.

This is how your component may look like:

import React, { useState } from 'react'
import { AnyColorFormat, Colorpicker } from 'antd-colorpicker'

const App = () => {
  const [color, setColor] = useState<AnyColorFormat>({
    r: 0,
    g: 0,
    b: 0,
    a: 0.5,
  })

  const onChange = (color: AnyColorFormat) => {
    setColor(color)
  }

  return (
    <div
      style={{ maxWidth: '500px', margin: '20px auto', paddingBottom: '50px' }}
    >
      <Colorpicker value={color} onChange={onChange} />
    </div>
  )
}

export default App

This is it! Enjoy!