Skip to content

Latest commit

 

History

History
122 lines (92 loc) · 6.49 KB

CONTRIBUTING.md

File metadata and controls

122 lines (92 loc) · 6.49 KB

Contribution guide

Vue3 + TS + Quasar

Welcome to the Vue3 + TS + Quasar GitHub showcases contribution guide.

We're glad to see that you'd love to contribute. This document will try to get you up to speed as fast and as smoothly as possible.

If you were instead looking to just run the application, then please read our README for details on how to do so.

Key Technologies used

  • Vue 3 - A progressive frontend framework.
  • GraphQL with Apollo - We use this for fetching data from the GitHub GraphQL API and it allows us to only retrieve the information we want at any given point in time.
  • Typescript - TypeScript is a strongly typed programming language that builds on JavaScript, giving you better tooling at any scale.
  • Quasar 2.x - A Vue.js based framework, which allows you as a web developer to quickly create responsive websites/apps in many flavours. It also contains several ready-made UI components that accelerate the development of this project.
  • Yarn - We'll be using this to manage our dependencies.

Other technologies used

  • Pinia - Pinia the official Vue3 recommended state management solution that offers a cleaner API and simpler API than VueX, it's predecessor. It is useful for managing global state in our application such as storing information about our currently logged in user.
  • Storybook - Storybook provides us with an interface that can be used by non-developers to make design decisions without needing to code. Each storybook acts as a sort of design document for the entire application and can further streamline the interactions between stakeholders/designers and the engineers that do the actual building of the product.

Project structure

This project uses the standard Quasar project directory structure with a few additional directories.

├── public/ # pure static assets (directly copied)
├── src/
│ ├── assets/ # dynamic assets (processed by webpack)
│ ├── components/ # .vue components used in pages & layouts
| |  ├── *.stories.ts # Storybook files
| |  ├── /index.ts # Re-exports our components for cleaner imports in other areas
| |── composables/ # vue composables
│ ├── css/ # CSS/Sass/... files for your app
| | ├── app.sass
| │ └── quasar.variables.sass # Quasar Sass variables for you to tweak
│ ├── layouts/ # layout .vue files
│ ├── pages/ # page .vue files
│ ├── boot/ # boot files (app initialization code)
│ ├── router/ # Vue Router
| | ├── index.js # Vue Router definition
| │ └── routes.js # App Routes definitions
│ ├── stores/ # Pinia Stores (if not using Vuex)
| | ├── index.js # Pinia initialization
| │ ├── <store> # Pinia stores...
| │ └── <store>...
│ ├── App.vue # root Vue component of your App
│ └── index.template.html # Template for index.html
├── src-ssr/ # SSR specific code (like production Node webserver)
├── src-pwa/ # PWA specific code (like Service Worker)
├── dist/ # where production builds go
│ ├── spa/ # example when building SPA
│ ├── ssr/ # example when building SSR
│ ├── electron/ # example when building Electron
│ └── ....
├── quasar.config.js # Quasar App Config file
├── babel.config.js # Babeljs config
├── jest.config.js # Jest config
├── .eslintignore # ESlint ignore paths
├── .eslintrc.js # ESlint config
├── .postcssrc.js # PostCSS config
├── .gitignore # GIT ignore paths
├── .prettierignore # prettier ignore paths
├── .prettierrc # prettier config
├── package.json # npm scripts and dependencies
├── CONTRIBUTION.md` # contribution guide for this showcase
└── README.md # readme for this showcase

Architectural decisions

Why Quasar?

Quasar has a large number of prebuilt vue components that are easily customizable. This saves us time by allowing us to focus on our app's functionality rather than the components and CSS required to make that happen.

Relevant interactions in the codebase

Who can access what is an important consideration when trying to build a maintainable codebase.

  • Composables should not call each other. If a composable needs another composable, then it must accept that composable through it's creator arguments
  • Custom CSS should be avoided in favour of Quasar CSS classes whenever possible. This makes it easier for a new entrant into the codebase to get up to speed.
  • Tests should ideally test the core functionality of whatever they are testing and not just check if a component is being mounted.

Naming conventions

Vue

  • Component names should use TitleCase
  • Each component should have a name attached to it when declaring it with defineComponent()

CSS

  • All class names should be in kebab-case
  • Custom styling should only be used in absence of an equivalent quasar class

JS/TS

  • ref s should be in camelCase
  • constants (non-reactive values) are in UPPERCASE_SNAKE_CASE
  • Every ref or variaible that does not have its type automatically inferred should have explicit types

Reporting bugs / Suggesting features

When reporting bugs or suggesting new features, please create an issue using the GitHub issue tracker.

Useful information to include

  • What operating system are you running on?
  • What version of NodeJS & package managers (npm, pnpm, yarn, etc)?
  • Which showcase are you having trouble with?
  • Branch you are experiencing the issue on
  • Description of the issue
  • Steps to reproduce the issue
  • Screenshots of the issue if the issue is visually observable

Best practices

  • Ensure that the issue you are creating has not yet been created or resolved
  • If your issue has been created but not resolved, leave a comment in the existing issue and upvote it to direct more attention towards it.