Q3 client

Most Q3 projects will use Gatsby JS for building and serving its production files. That's why we've created the gatsby-theme-q3 project, which configures most packages in this workspace so that you can begin building your app quickly.

If you're already up-and-running, scroll to the end for more in-depth documentation per package.

Getting started

This guide shows you how to setup a Q3 admin portal with a single collection. Since this is a headless workspace, you'll need an API, which you must build and deploy separately. For more information, visit the Q3 API repository.

Dependencies

Q3 has a lot of dependencies. Check our example app's package.json file for a full list with recommended versions.

Configurations

Environment variables

There's only a few environment variables that you need to define.

Name	Description
GATSBY_APP_BASE_URL*	The URL of your Q3 API
URL*	The production URL for this app

Folder structure

The tree below represents the end-state for this tutorial. As of v3, shadowing our theme's public pages (i.e. logic) is probably no longer necessary, as the design has become more customizable in other ways.

📦 server
📦 client
 ┣ 📂 src
 ┃ ┣ 📂 components
 ┃ ┃ ┣ 📂 Users
 ┃ ┃ ┃ ┣ 📜 index.js
 ┃ ┃ ┃ ┣ 📜 Users.jsx
 ┃ ┃ ┃ ┣ 📜 Users.test.jsx
 ┃ ┃ ┣ 📂 UsersAdd
 ┃ ┃ ┣ 📂 UsersGeneral
 ┃ ┃ ┗ 📜 index.js
 ┃ ┣ 📂 gatsby-theme-q3
 ┃ ┃ ┣ 📂 pages
 ┃ ┃ ┃ ┣ 📜 login.jsx
 ┃ ┃ ┃ ┣ 📜 password-change.jsx
 ┃ ┃ ┃ ┣ 📜 password-reset.jsx
 ┃ ┃ ┃ ┣ 📜 reverify.jsx
 ┃ ┃ ┃ ┗ 📜 verify.jsx
 ┃ ┣ 📂 pages
 ┃ ┃ ┣ 📜 app.jsx
 ┃ ┃ ┗ 📜 index.jsx
 ┣ 📂 static
 ┃ ┣ 📜 favicon.png
 ┃ ┗ 📜 logo.png
 ┣ 📂 tests
 ┣ 📜 gatsby-browser.js
 ┣ 📜 gatsby-config.js
 ┣ 📜 gatsby-node.js
 ┗ 📜 gatsby-ssr.js

Gatsby files

We're not going to cover why gatsby-* files exist. In fact, the browser, node and SSR variants are sometimes not even used. That said, the gatsby-config.js file is very important to Q3.

Using our setup helper function, you can get the build process wrapped up in just a few lines. Essentially, you just need to populate the meta data.

// gatsby-config.js

const config = require('gatsby-theme-q3/helpers').setup(
  {
    appDirectory: '/app',
    description: '',
    siteUrl: process.env.URL,
    title: '',
  },
  [], // any plugins you'd like to register
);

module.exports = config;

Some of Q3 admin's props will pick up on these settings. In most cases, the directory will remain /app, as that's the file under pages where we'll insert the magic.

Looking at app.jsx, you'll find the code deceivingly simple; it delegates a ton of responsible to Q3. Most features like state management, notifications, authorization, etc. come out-of-the-box. While you can pass props to alter the admin experience, you'll mainly interact with AppProps.pages, as that's how you register new collections in the UI.

// app.jsx
import React from 'react';
import { AdminRouter } from 'gatsby-theme-q3/src/components';
import { Dashboard, Users } from '../components';

export default () => (
  <AdminRouter
    AdminProps={{
      AppProps: {
        // will create custom components that inherit Q3 state and utilities
        customRoutes: [<Dashboard path="/" />],
        // will create templates that are highly dependent on Q3 builder functions
        pages: [Users].flat(),
      },
    }}
  />
);

More coming soon.

Packages API

• 🧰 Admin Docs
• 🔒 Audit Docs
• 📊 Charts Docs
• 🙊 Comments Docs
• ✉️ Email Editor Docs
• 🗃️ File Manager Docs
• ⌨️ Form Docs
• 🆘 Helpers Docs
• 📤 Queue Logs
• 📝 Rich Text

Upgrade guides

V3. to V4.

Q3 v3 underwent a massive design overhaul. A few components then underwent further functional changes, which lead to an early release of v4 to try and contain breaking changes.

Click here for v3. code branch

Breaking changes

• Notifications package requires v4 on the API server as well

V2. to V3.

Q3 V3. aims to cleanup the repository of unused packages and make project setup less intensive. For this reason, we've done away with locale and theme files, using Q3 API's domain feature on client init instead. When deploying over sub-domains, this allows the client to become multi-tenanted.

In addition to structural changes, v3 also brought about a new design. By becoming more hooks-based, we've managed to bring previously hidden features like file management and segments out into the forefront on mobile.

Breaking changes

Click here for v2. code branch

• Dropped react-i18next as a dependency
• In v3.3.2, q3-blocks left the repo
• Q3-api v3+ is now required due to reliance on its domains feature for setting up locale and theme
• gatsby-theme-q3 no longer supports contentful out-of-the-box

V1. to V2.

Q3 V2. requires fewer configurations and supports newer versions of its peer dependencies. Note that MUI continues to remain in v4. and we plan to upgrade that in sometime in 2022.

Breaking changes

Click here for v1. code branch

• Single gatsby-config.js file using theme’s setup helper
• AdminRouter component for handling all q3-admin configurations
• Notifications component inside profile
• ESlint, Prettier and Jest configurations now out-of-the-box
• Replacement package for react-i18next due to API changes