Skip to main content

The Quickstart Project

Scaffold Details
ComplexityIntermediate
Automated TestsYes
Installed PluginsLIGO, Taquito, Flextesa, Contract Types
Frontend DappYes
Wallet IntegrationYes
Repositoryhttps://github.com/pinnacle-labs/taqueria-scaffold-quickstart

Quickstart

In a rush? Get up and going immediately with the following steps:

  1. Scaffold the project by running:
taq scaffold https://github.com/pinnacle-labs/taqueria-scaffold-quickstart quickstart-project 
  1. Start the project by running:
npm run start
  1. 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)
caution

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

note

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:

  1. Install npm dependencies
  2. Run the required commands to build and deploy the Taqueria project
  3. 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:

  1. Build the /taqueria NPM project: npm run build - installs npm dependencies, including Taqueria plugins
  2. 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
  3. 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