The Quickstart Project
Scaffold Details | |
---|---|
Complexity | Intermediate |
Automated Tests | Yes |
Installed Plugins | LIGO, Taquito, Flextesa, Contract Types |
Frontend Dapp | Yes |
Wallet Integration | Yes |
Repository | https://github.com/pinnacle-labs/taqueria-scaffold-quickstart |
Quickstart
In a rush? Get up and going immediately with the following steps:
- Scaffold the project by running:
taq scaffold https://github.com/pinnacle-labs/taqueria-scaffold-quickstart quickstart-project
- Start the project by running:
npm run start
- Use the Dapp (served in your browser at http://localhost:3000) by connecting a wallet and using the web UI
Overview
Taqueria provides a starter project that you can use to get up and running quickly by using the taq scaffold
command
This project is a full stack dapp which includes:
- A React app frontend
- The Beacon Wallet integration
- A Taqueria project with the required smart contracts
This tutorial will walk you through the process of scaffolding the taqueria-scaffold-quickstart
project right from Taqueria and getting the project up and running on your local machine, and give you an understanding of how the project is structured so you can start modifying it to suit your needs
Requirements
To successfully follow this tutorial, you must ensure that:
- The Taqueria CLI binary has been installed locally and is available in your terminal
$PATH
- Docker Desktop is installed and registered in your terminal, and that the Docker daemon is currently running
- You are using Node.js v16.16 or later. (v17.x.x or later is not supported)
Currently the Taqueria VS Code Extension does not support the scaffold command. For best results, run the commands in this tutorial from the CLI
Scaffolding the Quickstart Project
Taqueria provides a task, taq scaffold
, which creates a new project locally from a scaffold project located in a git repo. Taqueria provides a project called taqueria-scaffold-quickstart
which will be used in this tutorial
The command for the scaffold task has this structure: taq scaffold <repo-url> [project-name]
. When run, Taqueria will create a new Taqueria project in the [project-name]
directory, and clone the <repo-url>
into that project directory
Run the following to scaffold the taqueria-scaffold-quickstart
project into the quickstart-project
directory:
taq scaffold https://github.com/pinnacle-labs/taqueria-scaffold-quickstart quickstart-project
Understanding the Project
Project Structure
Now that the project has been scaffolded, you can see the project structure in the quickstart-project
directory by changing directories:
cd quickstart-project
then listing the contents of the directory:
ls -al
This will give you an output that looks something this:
-rw-r--r-- 1 demoUser README.md
drwxr-xr-x 9 demoUser app
drwxr-xr-x 5 demoUser taqueria
-rw-r--r-- 1 demoUser package.json
-rw-r--r-- 1 demoUser package-lock.json
As you can see, there are two executable directories, app
and taqueria
. The app
directory contains the frontend React app, and the taqueria
directory contains the Taqueria project which includes the smart contracts and Taqueria plugins
Use of Node.js
This project uses multiple instances of Nodejs to build and run the project in a simple and easy way
There are 3 node apps in total in this project:
- The React frontend app that lives in '/app'
- The Taqueria project located in
/taqueria
- The project root itself
Each directory is a Node app which includes with a package.json
file and a package-lock.json
file. You will notice that the package.json
file in the app
and taqueria
directories are specific to each app, containing the dependencies, settings, and scripts required for each app
The package-lock.json
file contains the dependencies for each project, and is used to ensure consistency. You should generally not edit this file directly
App Specific Settings
If you open the package.json file, you will see the node configuration required for each project
Taqueria package.json
from /taqueria
dir looks like this:
{
"private": true,
"name": "@local/contract",
"scripts": {
"build": "taq compile && taq generate types ../app/src/types",
"start:local": "npm run build && taq start sandbox local && taq deploy",
"stop:local": "taq stop sandbox local"
},
"dependencies": {
"@taqueria/plugin-contract-types": "latest",
"@taqueria/plugin-flextesa": "latest",
"@taqueria/plugin-ligo": "latest",
"@taqueria/plugin-taquito": "latest",
"@taquito/taquito": "^11.2.0"
}
}
While the React app package.json
from /app
dir looks like this:
{
"name": "example-app",
"version": "0.1.0",
"private": true,
"dependencies": {
...
},
"scripts": {
"start": "react-app-rewired start",
"build": "react-app-rewired build",
"test": "react-app-rewired test",
"eject": "react-scripts eject"
},
"eslintConfig": {
"extends": [
"react-app",
"react-app/jest"
]
},
"browserslist": {
"production": [
...
],
"development": [
...
]
},
"proxy": "http://localhost:20000"
}
As you can see, each project has a different set of dependencies, scripts, and settings. The package.json
files are used to specify the dependencies, scripts, and settings for each project. This means each project can be built, started, and used independently
Root Project Settings
The package.json
file in the project root is used to bundle both apps together into a single node app that can be run from a single command. It changes directories looks like this:
{
"private": true,
"scripts": {
"setup": "npm run setup:taqueria && npm run setup:app",
"setup:taqueria": "cd ./taqueria && npm install && taq init",
"setup:app": "cd ./app && npm install",
"start": "npm run build:taqueria && npm run start:app",
"build:taqueria": "cd ./taqueria && npm run build",
"start:app": "cd ./app && npm run start",
"start:local": "npm run start:taqueria:local && npm run start:app",
"start:taqueria:local": "cd ./taqueria && npm run start:local",
"stop:local": "npm run stop:taqueria:local",
"stop:taqueria:local": "cd ./taqueria && npm run stop:local"
}
}
Building and Starting the Project
The root Node project contains setup
and start
scripts which can be run together on a single line to build, deploy, and launch the dapp. This process involves the following steps:
- Install npm dependencies
- Run the required commands to build and deploy the Taqueria project
- Start up the React app
From the root of the project, run the following command to build and start the project:
npm run setup && npm run start
This will result in your browser opening to a simple webpage that has a connect
button for the Beacon wallet integration
It's important here to understand what steps occur implicitly during this so you can understand how the different plugins and files are in Taqueria
Building and Deploying the Taqueria Project
If you inspect the scripts in /taqueria/package.json
, you will see the following actions occur on the Taqueria project implicitly when the setup command is run:
- Build the
/taqueria
NPM project:npm run build
- installs npm dependencies, including Taqueria plugins - Compile the ligo contract:
taq compile
- uses the LIGO Taqueria plugin to compile the smart contract located in/taqueria/contracts
, outputing compiled Michelson.tz
files in the/artifacts
directory - Generates TS types:
taq generate types
- uses the Taqueria Type Generator plugin to generate TS types from the compiled smart contract, and install them into the React app (/app/types
) for use with Taquito in the frontend