1 of 8

Quick Start Tutorial

Getting Started

Aloha! Let’s test out running Frigg locally by cloning and installing a quick start template app.

Prerequisites

You'll need to do the following before continuing:

Make sure you have node and npm installed
Create a free hosted MongoDB cluster through MongoDB Atlas OR install MongoDB locally
- You'll need to create a db admin user and you'll want your connection string.

Overview

Create Frigg App will generate a Frigg application that within a few minutes is deployable to your own infrastructure accounts. Let's get Create Frigg App going and unpack the "magic" as we go.

Create Frigg App

Use npx to use the latest generator code, and just pass it whatever you want to name your Frigg application.

Note on naming: we recommend thinking of your Frigg app as a microservice that powers integrations; naming it something like "my-app-integrations" is a good fit

npx create-frigg-app [my-app-integrations]
cd [my-app-integrations]

Congrats! You've just successfully scaffolded and installed your Frigg application.

Configuration

Frontend

You will have to set up your own config files for the frontend of your application with:

cd frontend
cp .env.example .env

Backend

Currently, configuration is managed in two places for the backend. You can see the backend configuration here: backend/src/configs/*.json but you will also need a .env file in /backend.

cd backend
cp .env.example .env

Start Your Application

Let's spin it up to explore more:

npm run start

Your browser should open to http://localhost:3000, and the backend should spin up an API route at http://localhost:3001/dev/api

Exploring the App

Frontend overview

Running npm start at the root of your Frigg application repo will run npm start on both the /backend and /frontend directories. Let's unpack each.

The frontend is a cookie cutter React application built with Create React App and Tailwind CSS and Tailwind UI. It leverages the Frigg React component library for the Integration Management page. This is the core piece to pay attention to for your own application. You can read more about Frontend options and concepts with Frigg here.

We provide a very lightweight/basic user login flow and dashboard. Go ahead and try logging in or creating an account.

// Image of login screen

Note that when you attempt to log in, you will receive an error. We'll come back to this in a moment, but the TL;DR is that we need to plug in a database for the backend to talk to.

Backend overview

The backend is oriented around the serverless.com framework. When you run npm start, it runs the command to use the serverless-offline plugin. Critical to note is that this supports basic functionality (API => function invocation, or schedule => function invocation), it does not support all events that you may be relying on to power your integrations. In other words, you can run Authentication and Configuration, but the entirety of your Frigg applications' backend will not run using this command. For that, see "Running Frigg Locally."

The Backend is comprised of the following folder structure:

├── backend
│   ├── app.js
│   ├── jest.config.js
│   ├── package-lock.json
│   ├── package.json
│   ├── scripts
│   │   ├── set-up-tests.js
│   │   └── tear-down-tests.js
│   ├── serverless.yml
│   ├── setupEnv.js
│   ├── src
│   │   ├── configs
│   │   │   └── dev.json
│   │   ├── handlers
│   │   │   ├── createHandler.js
│   │   │   ├── examplePollWorker.js
│   │   │   ├── exampleQueuer.js
│   │   │   └── http
│   │   │       ├── auth.js
│   │   │       └── demo.js
│   │   ├── managers
│   │   │   ├── IntegrationConfigManager.js
│   │   │   ├── SyncManager.js
│   │   │   ├── UserManager.js
│   │   │   ├── entities
│   │   │   │   └── ExampleManager.js
│   │   │   ├── integrations
│   │   │   │   └── ExampleIntegrationManager.js
│   │   │   └── migrations
│   │   │       ├── MigrationManager.js
│   │   │       └── ExampleMigrator.js
│   │   ├── models
│   │   │   ├── IndividualUser.js
│   │   │   ├── OrganizationUser.js
│   │   │   ├── Token.js
│   │   │   └── User.js
│   │   ├── objects
│   │   │   └── sync
│   │   │       └── ExampleLeadSync.js
│   │   ├── routers
│   │   │   ├── auth.js
│   │   │   ├── demo.js
│   │   │   ├── middleware
│   │   │   │   ├── loadUserManager.js
│   │   │   │   └── requireLoggedInUser.js
│   │   │   └── user.js
│   │   ├── utils
│   │   │   ├── FormatPatchBody.js
│   │   │   ├── QueuerUtil.js
│   │   │   ├── RouterUtil.js
│   │   │   └── fakeWindow.js
│   │   └── workers
│   │       └── examples
│   │           ├── ExamplePollWorker.js
│   │           ├── ExampleQueuer.js
│   │           ├── InitialSync.js
│   │           ├── WebHookSync.js
│   │           └── WebhookWorker.js
│   ├── test
│   │   ├── api.integration.test.js
│   │   ├── managers
│   │   │   └── integrations
│   │   │       └── ExampleIntegration.test.js
│   │   ├── mocks
│   │   ├── routers
│   │   │   ├── auth.test.js
│   │   │   └── test-auth.test.js
│   │   └── utils
│   │       ├── Authenticator.js
│   │       ├── CreateIntegrationsTest.js
│   │       ├── ModelTestUtils.js
│   │       ├── TestUtils.js
│   │       ├── TextReportFile.js
│   │       └── reusableTestFunctions
│   │           └── integration.js
│   └── webpack.config.js
├── frontend
│   ├── package-lock.json
│   ├── package.json
│   ├── postcss.config.js
│   ├── public
│   │   ├── FriggLogo.svg
│   │   ├── LeftHooks-square.png
│   │   ├── _redirects
│   │   ├── assets
│   │   │   ├── media
│   │   │   │   └── Back_arrow.svg
│   │   │   └── type
│   │   │       └── FranklinGothicURW
│   │   │           ├── FranklinGothicURW-Boo.otf
│   │   │           ├── FranklinGothicURW-BooIta.otf
│   │   │           ├── FranklinGothicURW-Dem.otf
│   │   │           ├── FranklinGothicURW-DemIta.otf
│   │   │           ├── FranklinGothicURW-Lig.otf
│   │   │           ├── FranklinGothicURW-Med.otf
│   │   │           └── FranklinGothicURW-MedIta.otf
│   │   ├── favicon.ico
│   │   ├── hubspot_logo.svg
│   │   ├── index.html
│   │   ├── lh_logo.png
│   │   ├── manifest.json
│   │   └── salesforce_logo.svg
│   ├── src
│   │   ├── App.js
│   │   ├── AppRouter.js
│   │   ├── __tests__
│   │   │   ├── Integration.test.js
│   │   │   ├── Login.test.js
│   │   │   └── Logout.test.js
│   │   ├── actions
│   │   │   ├── auth.js
│   │   │   ├── integrations.js
│   │   │   ├── logout.js
│   │   │   ├── modal.js
│   │   │   └── modalForm.js
│   │   ├── api
│   │   │   └── api.js
│   │   ├── components
│   │   │   ├── Auth.js
│   │   │   ├── AuthRedirect.js
│   │   │   ├── CreateUser.js
│   │   │   ├── Data.js
│   │   │   ├── FormValidator.js
│   │   │   ├── Integration
│   │   │   │   ├── IntegrationDropdown.js
│   │   │   │   ├── IntegrationHorizontal.js
│   │   │   │   ├── IntegrationList.js
│   │   │   │   ├── IntegrationSkeleton.js
│   │   │   │   ├── IntegrationVertical.js
│   │   │   │   ├── ToggleSwitch.js
│   │   │   │   └── index.js
│   │   │   ├── Login.js
│   │   │   ├── Logout.js
│   │   │   ├── ModalForm.js
│   │   │   ├── Navbar.js
│   │   │   └── Sidebar.js
│   │   ├── frigg.config.js
│   │   ├── index.css
│   │   ├── index.js
│   │   ├── pages
│   │   │   ├── IntegrationsPage.js
│   │   │   └── SettingsPage.js
│   │   ├── reducers
│   │   │   ├── auth.js
│   │   │   ├── index.js
│   │   │   ├── integrations.js
│   │   │   ├── logout.js
│   │   │   ├── modal.js
│   │   │   └── modalForm.js
│   │   ├── store
│   │   │   └── index.js
│   │   └── utils
│   │       ├── IntegrationUtils.js
│   │       ├── history.js
│   │       ├── logger.js
│   │       └── withRouter.js
│   └── tailwind.config.js
├── package-lock.json
└── package.json

How it works

As you might have noticed, you use both a serverless instance and a client side react app to access the Frigg API modules. The flow looks like this:

Connecting to the Database

Frigg has a fairly straightforward data model

Currently we connect to a MongoDB cluster using Mongoose. Recommendation is MongoDB Atlas, fast and free to spin up a test cluster.
Follow instructions to create
Copy and paste yours to the config/dev.json file

Installing an API Module

npm install @friggframework/api-module-hubspot in the backend
Default display override by adding to ConfigManager
Override or add helper functions by creating a HubSpotManager.js in /managers/entities
Copy over ExampleIntegrationManager.js and corresponding test file
Good to go!

Building your first integration

HubSpotIntegrationManager.js
getExample function, add

const contacts = await this.targetInstance.api.listContacts()
return contacts.results

Go to HubSpot, sign up for a developer account
Create an Application
Navigate to Settings
OAuth
Copy Client ID and Secret into /config/dev.json under HUBSPOT_CLIENT_ID and HUBSPOT_CLIENT_SECRET respectively
Add http://localhost:3000/redirect/hubspot to the redirect URI
Navigate to backend, run npm start
Go to the dashboard and reload if you haven't yet. Tada! Your first integration

Testing the Integration

Mocks
proxyquire
If you're using queues...

Next Steps

Deeper dive into What Makes an Integration
Reach out to Left Hook or the community for help!
Add your own API Module
Integrate Frigg into your existing stack
Customize the authentication
Add more complexity to your integration
Think in categories

Exploring the App

Frontend overview

Running npm start at the root of your Frigg application repo will run npm start on both the /backend and /frontend directories. Let's unpack each.

We provide a very lightweight/basic user login flow and dashboard. Go ahead and try logging in or creating an account.

// Image of login screen

Note that when you attempt to log in, you will receive an error. We'll come back to this in a moment, but the TL;DR is that we need to plug in a database for the backend to talk to.

Backend overview

The Backend is comprised of the following folder structure:

├── backend
│   ├── app.js
│   ├── jest.config.js
│   ├── package-lock.json
│   ├── package.json
│   ├── scripts
│   │   ├── set-up-tests.js
│   │   └── tear-down-tests.js
│   ├── serverless.yml
│   ├── setupEnv.js
│   ├── src
│   │   ├── configs
│   │   │   └── dev.json
│   │   ├── handlers
│   │   │   ├── createHandler.js
│   │   │   ├── examplePollWorker.js
│   │   │   ├── exampleQueuer.js
│   │   │   └── http
│   │   │       ├── auth.js
│   │   │       └── demo.js
│   │   ├── managers
│   │   │   ├── IntegrationConfigManager.js
│   │   │   ├── SyncManager.js
│   │   │   ├── UserManager.js
│   │   │   ├── entities
│   │   │   │   └── ExampleManager.js
│   │   │   ├── integrations
│   │   │   │   └── ExampleIntegrationManager.js
│   │   │   └── migrations
│   │   │       ├── MigrationManager.js
│   │   │       └── ExampleMigrator.js
│   │   ├── models
│   │   │   ├── IndividualUser.js
│   │   │   ├── OrganizationUser.js
│   │   │   ├── Token.js
│   │   │   └── User.js
│   │   ├── objects
│   │   │   └── sync
│   │   │       └── ExampleLeadSync.js
│   │   ├── routers
│   │   │   ├── auth.js
│   │   │   ├── demo.js
│   │   │   ├── middleware
│   │   │   │   ├── loadUserManager.js
│   │   │   │   └── requireLoggedInUser.js
│   │   │   └── user.js
│   │   ├── utils
│   │   │   ├── FormatPatchBody.js
│   │   │   ├── QueuerUtil.js
│   │   │   ├── RouterUtil.js
│   │   │   └── fakeWindow.js
│   │   └── workers
│   │       └── examples
│   │           ├── ExamplePollWorker.js
│   │           ├── ExampleQueuer.js
│   │           ├── InitialSync.js
│   │           ├── WebHookSync.js
│   │           └── WebhookWorker.js
│   ├── test
│   │   ├── api.integration.test.js
│   │   ├── managers
│   │   │   └── integrations
│   │   │       └── ExampleIntegration.test.js
│   │   ├── mocks
│   │   ├── routers
│   │   │   ├── auth.test.js
│   │   │   └── test-auth.test.js
│   │   └── utils
│   │       ├── Authenticator.js
│   │       ├── CreateIntegrationsTest.js
│   │       ├── ModelTestUtils.js
│   │       ├── TestUtils.js
│   │       ├── TextReportFile.js
│   │       └── reusableTestFunctions
│   │           └── integration.js
│   └── webpack.config.js
├── frontend
│   ├── package-lock.json
│   ├── package.json
│   ├── postcss.config.js
│   ├── public
│   │   ├── FriggLogo.svg
│   │   ├── LeftHooks-square.png
│   │   ├── _redirects
│   │   ├── assets
│   │   │   ├── media
│   │   │   │   └── Back_arrow.svg
│   │   │   └── type
│   │   │       └── FranklinGothicURW
│   │   │           ├── FranklinGothicURW-Boo.otf
│   │   │           ├── FranklinGothicURW-BooIta.otf
│   │   │           ├── FranklinGothicURW-Dem.otf
│   │   │           ├── FranklinGothicURW-DemIta.otf
│   │   │           ├── FranklinGothicURW-Lig.otf
│   │   │           ├── FranklinGothicURW-Med.otf
│   │   │           └── FranklinGothicURW-MedIta.otf
│   │   ├── favicon.ico
│   │   ├── hubspot_logo.svg
│   │   ├── index.html
│   │   ├── lh_logo.png
│   │   ├── manifest.json
│   │   └── salesforce_logo.svg
│   ├── src
│   │   ├── App.js
│   │   ├── AppRouter.js
│   │   ├── __tests__
│   │   │   ├── Integration.test.js
│   │   │   ├── Login.test.js
│   │   │   └── Logout.test.js
│   │   ├── actions
│   │   │   ├── auth.js
│   │   │   ├── integrations.js
│   │   │   ├── logout.js
│   │   │   ├── modal.js
│   │   │   └── modalForm.js
│   │   ├── api
│   │   │   └── api.js
│   │   ├── components
│   │   │   ├── Auth.js
│   │   │   ├── AuthRedirect.js
│   │   │   ├── CreateUser.js
│   │   │   ├── Data.js
│   │   │   ├── FormValidator.js
│   │   │   ├── Integration
│   │   │   │   ├── IntegrationDropdown.js
│   │   │   │   ├── IntegrationHorizontal.js
│   │   │   │   ├── IntegrationList.js
│   │   │   │   ├── IntegrationSkeleton.js
│   │   │   │   ├── IntegrationVertical.js
│   │   │   │   ├── ToggleSwitch.js
│   │   │   │   └── index.js
│   │   │   ├── Login.js
│   │   │   ├── Logout.js
│   │   │   ├── ModalForm.js
│   │   │   ├── Navbar.js
│   │   │   └── Sidebar.js
│   │   ├── frigg.config.js
│   │   ├── index.css
│   │   ├── index.js
│   │   ├── pages
│   │   │   ├── IntegrationsPage.js
│   │   │   └── SettingsPage.js
│   │   ├── reducers
│   │   │   ├── auth.js
│   │   │   ├── index.js
│   │   │   ├── integrations.js
│   │   │   ├── logout.js
│   │   │   ├── modal.js
│   │   │   └── modalForm.js
│   │   ├── store
│   │   │   └── index.js
│   │   └── utils
│   │       ├── IntegrationUtils.js
│   │       ├── history.js
│   │       ├── logger.js
│   │       └── withRouter.js
│   └── tailwind.config.js
├── package-lock.json
└── package.json

How it works

As you might have noticed, you use both a serverless instance and a client side react app to access the Frigg API modules. The flow looks like this: