Getting Started with the Sign In With Ronin Starter Pack

Welcome to the Sign In With Ronin (SIWR) Starter Pack Setup Tutorial!

This tutorial is designed to help junior to intermediate level web3 developers get the SIWR Starter Pack web app template (explore the live demo here) up and running locally to accelerate the time to building and launching their own Ronin-enabled projects.

To keep things succinct, this tutorial assumes a baseline knowledge of the systems and skills necessary to get a full stack web application up and running including terminal commands, the JavaScript language (and some TypeScript), Node.js runtime environment, Git version control, and package managers such as Yarn.

However, novice or aspiring web devs may find the outline and links below useful to help jumpstart their learning process and, once familiar with the relevant systems, can return here and follow these instructions to get their new project up and running.

Advanced users, feel free to fork/clone the code in whatever way works best for you and start hacking!

Tools we’ll use for this tutorial (you’ll need to have these downloaded):

• VS Code IDE for code writing and management
• Git Bash for git and terminal commands
• Yarn Package Manager for installing and managing packages
• Node.js as our core runtime environment

Services we’ll use for this tutorial (these we’ll set up along the way):

• GitHub for remote git repository management
• MongoDB non-relational database for data persistence
• Vercel for domain hosting and git repo continuous integration

Packages that the SIWR Starter Pack template is built on (these come bundled with this package, no external downloads necessary):

• Next.js full stack React-based web application framework
• NextAuth.js authentication and server-side session management
• Ethers.js interface for EVM Blockchains
• Mongoose.js object modeling for Node.js and MongoDB
• Chakra-UI front end design and component library

Lets get started!

Set Up Your Local Repository

The simplest way to get started hacking and adapting the SIWR Starter Pack template for your own Ronin-enabled projects is to fork the repo to your own GitHub account and then clone it down to your local machine:

• Log in to your GitHub account or create one at https://github.com/signup.
• Navigate to the SIWR Starter Pack GitHub page and fork the repo to your own account:

• You can now clone the forked repo to your local machine. To do so, first launch VS Code, press “Ctrl + `” (backtick) to open the terminal, and then open a new git bash terminal in a suitable parent directory (make sure you have Git Bash installed!).

• Now, return to the forked repo on GitHub and copy the the remote URL (I recommend using the HTTPS URL method if you’re still new to this process):

• Back in your VS Code terminal, use the URL to execute the following command (note that <your-username> should be populated with your own GitHub username):

git clone https://github.com/<your-username>/siwr-starter-pack.git

• Once the cloning completes, change your directory down into the newly cloned repo and install the necessary packages with the yarn command (make sure you have Yarn Package Manager installed and enabled!):

cd siwr-starter-pack/
yarn

• Once the packages are installed (this may take a few minutes), you will see the entire template file structure that composes the SIWR Starter Pack on the left panel of VS Code, feel free to explore around!

• At this point you can now also run your own local demo by executing the following command in your VS Code terminal:

yarn dev

• This will automatically start a local server running on port 3000, which can be viewed by visiting http://localhost:3000 in your browser of choice.
• *Note that at this point in the tutorial your database is not yet set up so you won’t be able to do much, and you may receive some error messages in your terminal. When you’re done exploring, press “Ctrl + C” in your terminal to stop the local host.*

Congrats, you now have the SIWR Starter Pack code running locally!

Set Up Your Database

Now that you have a runnable template, its time to hook it up to a database to store user account information and any other data relevant to your project such as Axie data, payment data, game data, etc. This portion of the tutorial assumes you do not have a personal MongoDB account — existing MongoDB users may proceed with setting up their own database and move on to the next section.

• New users — create a MongoDB account and set up your first project by filling in the prompts in the “Welcome to Atlas!” window with “Build a new application”, a relevant or custom application type, and JavaScript as the preferred language, then click “Finish”:

• On the next page, choose the free database tier, a cloud provider, region, and name of the cluster (the set of servers that host your database), and then press “Create”:

• Create a username and password for secure access to your database, and press “Create User”:

• Scroll down to the connection settings, keep “My Local Environment” selected, enter “0.0.0.0/0” (to enable access for all domains) into the “IP Address” field, press “Add Entry”, then press “Finish and Close”:

• Then press “Go to Databases” in the modal window:

• Once your cluster is up and running (may take a few minutes), click on “Connect”:

• When the modal window pops up, click “Connect your application”:

• Leave the driver and version settings as they are, and then copy the MongoDB connection string to your clipboard (keep the stuff that is blued-out to yourself!):

• Now return back to VS Code, rename the file “.env.local.example” to “.env.local”, open it, and paste your personal connection string as the value for both DEV_PLACEHOLDER and PLACEHOLDER as we will need to modify these strings a bit to finalize the configuration:

• Create a relevant name for your development database, something like PROJECTNAME_DEV, and replace the dummy name SIWR_DEV that is currently set as DEV_DB_NAME to this new name. Also update the production database DB_NAME from SIWR to PROJECTNAME:

• Then, insert your new database names into your personal connection strings listed in DEV_PLACEHOLDER and PLACEHOLDER in the place where DEV_DB_NAME and DB_NAME are located within the dummy connection strings that are currently set for DEV_MONGO_URI and MONGO_URI, respectively. Also be sure to update the <password> text to the password you created in the “Create User” step above:

• Now copy and paste your updated personal connection strings from DEV_PLACEHOLDER and PLACEHOLDER and replace the current dummy string for the value of DEV_MONGO_URI and MONGO_URI (keep the quotations):

• Your database and local dev environment should now be connected! Run your local host once more with the following command and navigate to http://localhost:3000 in your browser:

yarn dev

• Once the page finishes loading, try connecting your Ronin wallet by pressing the “Connect” button in the nav bar — you should be sent to the Axie DAO Single Sign On (SSO) provider page:

• On the Axie DAO SSO, click “Sign Message” to initiate the signing of a cryptographic message as part of the Sign In With Ronin process:

• This will prompt your Ronin wallet — review the message and then click “Confirm” to complete your signature:

• After signing, you will be redirected back to your SIWR template site to create an account with a username and password for your new project, then press “Create Account” :

• Congrats, you have your first user!

• As a final step, we will grant your new account admin privileges — to do this, navigate to your MongoDB database on https://www.mongodb.com/ and click on “Browse Collections”:

• On the left panel of the next page you should see your new database name as PROJECTNAME_DEV, and a set of collections pre-defined in the SIWR Starter Pack. Click on “accounts” if it its not already selected, and here you should see the account info of your first user (you)! In the data object (also known as a “document”), click on the “user” field to see the user information, then double click on the word “user” that is set as the value for the “role” key. Replace the “user” text with the word “admin”, and then press the “UPDATE” button.

• Your account now has admin privileges for your site! Currently, the SIWR Starter Pack template does not have much in the way of admin functionality, but you can write your own functions to check the value of a user’s “role” during a browsing session and dynamically render content to admins such as an admin panel or admin buttons on various pages.

Congrats, your project is now fully set up to begin hacking locally!

Set Up Your Live Deployments

The last portion of this tutorial will guide you through hosting your project on a live site using Vercel. If you are just itching to get started experimenting or implementing an idea of yours, you can skip this section and come back when you’re ready to test a live version deployed to the internet. If you’d like to incorporate this part up-front and include live deployments into your development cycle from the start, follow the next few steps to get your site hosted online for free!

• Navigate to Vercel and click on the “Sign Up” button at the top right corner of the page and sign up using your email address or your GitHub, GitLab or Bitbucket account.
• After signing up, you will be taken to the dashboard. Click on the “Import Project” button, or the “Add New…” button and then select “Project”:

• Find the repository you want to deploy in the list and click “Import”:

• *Note: If you’re following along immediately from the previous MongoDB setup process, you should select the forked version of the SIWR Starter Pack repo that now exists on your personal GitHub account. However, if you’re returning here after building/customizing your site and have deployed an alternative remote repo to your GitHub account that is more relevant to your specific project, then select that one here instead!*
• Configure your project settings: set a Project Name, select “Next.js” as your Framework Preset, keep your root directory as “./”, and then click on the “Environment Variables” section and add each of the environment variables from the “.env.local” file from your local codebase on VS Code, including the NEXTAUTH_SECRET, DEV_MONGODB_URI, DEV_DB_NAME, MONGODB_URI, and DB_NAME, and then click “Deploy”:

• *Note: Do not copy over any quotation marks from the URI values in your “.env.local” file. Also, do not copy over the “NODE_ENV=development” environment variable into your Vercel setup.*
• Wait for the deployment process to complete. Once it’s finished, you can click on the URL provided or the “Visit” button to see your deployed app!

• To set up a live development/staging domain, go back to Vercel and navigate to your environment variables under “Settings” > “Environment Variables”. Scroll down and update all 4 of your database variables by clicking on the 3 dots on the right side and then click “Edit”:

• Scroll down and update your production variables, DB_NAME and MONGODB_URI, to be used for the “Production Environment” (checkbox), and set your development variables, DEV_DB_NAME and DEV_MONGODB_URI to be used for “Preview Environment” only. This will allow you to access the development database you’ll be using with your local development environment on your live staging site when deploying to a development branch of your repository:

• At this point you may also find it useful to set up staging protections on your live development site so that updates to the site may be made and viewed strictly by admins or VIPs only. To do so, include STAGING=true as an additional environment variable for the “Preview Environment”, and then press “Save”:

• With your environment variables set up, you can create and deploy a development branch of your repo which will automatically build a staging site connected to your development database. To do so, go back to VS Code and execute the following commands into your terminal:

git branch dev
git checkout dev
git push -u origin dev

• Now, if you navigate to your “Deployments” in Vercel, you should see both your main (Production) and dev (Preview) deployments!

• Any time you push changes to your GitHub repository for either the “main” or “dev” branches, Vercel will automatically deploy those changes from the selected branch with the respective environment variables and notify you of any build errors that may occur along the way.

Congrats! You now have a live staging and production site connected to your database and set up with continuous integration via Vercel and GitHub!

Closing Thoughts

Ok, that’s it for this tutorial! For more information about the various components of the SIWR Starter Pack code base and some best practices on how to use them, please see the README.md file on the SIWR Starter Pack GitHub repository.

As a final note — I would love to hear from you if you use the SIWR Starter Pack to help jump start your Ronin-enabled project! Let me know in the comments here, on the GitHub Repo, or on Twitter regarding what you found helpful and/or confusing so I can continue to improve it over time!

Also, let me know if there are other features you would like to see added and I can expand on the package and tutorial to include those (some ideas for this are already in the works so stay tuned)!

Thanks for reading and happy hacking!

❤ w0nd3r

If you found this tutorial or package useful and would like to donate to w0nd3r, use the following addresses:

• Ronin: ronin:8aa23faa9540090ae84c57378987889941244d8e
• Ethereum: w0nd3r.eth (0xF5447b29dE5518968718D50d37939F44946d9F62)