SaaS Chariot

SaaS Chariot is an opinionated framework to rapidly develop SaaS products. This repository acts as a template for a SaaS Chariot project.

Initiating a Project

How to Fork

To create a new project based on this framework, do not use the 'fork' feature of GitHub. Instead, follow these steps:

1. On GitHub, create a new empty repository, let's call this the project repo.

2. git clone the project repo locally and cd into it.

3. Add this, the main branch of the framework repo, as an upstream remote to the project repo clone, let's name this remote framework.:

   
     git remote add framework https://github.com/ParkourOps/saas-chariot
   
   

4. Create a local branch on the project repo clone called framework which will reflect the main branch of the framework repository.

   
     git fetch framework main
   
     git checkout -b framework --track framework/main
   
   

5. Create the main branch on the project repo.

   
     git checkout -b main
   
     git push -u origin main
   
   

6. Install the Node dependencies and get developing!

   
     npm install
   
   

Features

Framework

• TypeScript is used to ensure consistency in the structure of data and the interfaces to runtime components that use data.

• Vue 3 is used as the overall framework to implement the Single Page Application (SPA).

• Daisy UI is used as the primary styling framework; it provides a level of abstraction (and therefore consistency) over Tailwind CSS.

• SCSS is used to create and manage custom styling via dynamic stylesheets.

Analytics and Logging

• MixPanel is used to track user actions.
• Hotjar is used to capture user behaviour metrics.

Authentication

• Firebase Authentication is used for federated sign in.

Data Storage

• Firestore Database is used to store data in document collections.

File Storage

• Firebase Storage is used to store files. It is a wrapper over Google Cloud Storage, a managed cloud object storage service.

Customer Feedback

• Tawk.to is used to capture user feedback and have a live chat with visitors.

Subscription and Billing

• Firebase Functions are used to automatically create a user profile in the database.

User Alerts

Saas Chariot uses a number of ways to notify users about an event:

• In-App Notifications:
  • Popup Alerts
  • Toast Notifications

Note: Currently, In-App Notifications only originate from the frontend.

• Email Notifications: *

Folder Structure

Application source code is stored in the src folder.

Structure of the src folder is inspired by this guide:

• assets contains anything that isn't code:

  • images
  • icons
  • fonts
  • styles is where SCSS stylesheets are stored. Make sure to @import all global stylesheets in main.scss.

• components contains SFCs (<component-name>.vue, where <component-name> is in PascalCase") used across the project, organised into the following subfolders:

  • ui to store UI components like cards, modals, and buttons.
  • form to store components specifically used in forms such as checkboxes, inputs, date pickers, etc.
  • layouts to store reusable layout components such as sidebars, navigation bars, containers, etc.
  • modals to store modals implemented using <Modal></Modal> as root component, shown using the ModalStack plugin's $showModal(<component>, <component props as obj>) function.

• configs contains interfaces to application configurations; the configurations themselves are passed into Vite as environment variables.

• data is used to store data assets such as JSON files.

• state is used to store global state in the form of Pinia stores.

• features contains one folder for each feature in the application. Each feature folder may contain:

  • (any folders listed here, apart from global folders such as features, plugins and state.)

• libraries contains facades/abstractions for the various different libraries used in the project. Using facades means libraries don't have to be directly imported into rest of application codebase multiple times, making it easier to update/replace library or customise it for own use.

• plugins contains Vue plugins; Vue plugins are always applied globally.

• pages contains SFCs, each SFC represents a unique page (<page-name>.vue) where <page-name> is in "PascalCase".

  • If the page SFC must use other SFCs that will only be used on the page, create a folder called <page-name>, store the page SFC as <page-name>.vue and others as <component-name>.vue.
  • It may be helpful to organise pages into arbitrary folders, in which case the name of such a folder must abide by the generic "kebab-case" used throughout the project (with exception of Vue components including pages).

• services contains code used to interface with external APIs (instead of litering rest of application codebase with API interaction code).

• utilities contains files that export simple pure functions such as formatters that do not cause side effects.

Recommended IDE Setup

VSCode + Volar (and disable Vetur) + TypeScript Vue Plugin (Volar).

Type Support for .vue Imports in TS

TypeScript cannot handle type information for .vue imports by default, so we replace the tsc CLI with vue-tsc for type checking. In editors, we need TypeScript Vue Plugin (Volar) to make the TypeScript language service aware of .vue types.

If the standalone TypeScript plugin doesn't feel fast enough to you, Volar has also implemented a Take Over Mode that is more performant. You can enable it by the following steps:

1. Disable the built-in TypeScript Extension
   1. Run Extensions: Show Built-in Extensions from VSCode's command palette
   2. Find TypeScript and JavaScript Language Features, right click and select Disable (Workspace)
2. Reload the VSCode window by running Developer: Reload Window from the command palette.

Customize configuration

See Vite Configuration Reference.

Project Setup

npm install

Compile and Hot-Reload for Development

npm run dev

Type-Check, Compile and Minify for Production

npm run build

Run Unit Tests with Vitest

npm run test:unit

Run End-to-End Tests with Playwright

# Install browsers for the first run
npx playwright install

# When testing on CI, must build the project first
npm run build

# Runs the end-to-end tests
npm run test:e2e
# Runs the tests only on Chromium
npm run test:e2e -- --project=chromium
# Runs the tests of a specific file
npm run test:e2e -- tests/example.spec.ts
# Runs the tests in debug mode
npm run test:e2e -- --debug

Lint with ESLint

npm run lint

Things To Do

• Move plugins to framework_features
• Auto-import all plugin features
• Update docs