vue3-bulma-template

A simple to use TypeScript frontend template based on vue3 (Composition API) and bulma.

This TypeScript template helps you get started with developing Vue 3 applications quickly and easily, and is designed for building mobile friendly web applications with persistent state across sessions.

Get started by

1. Downloading the template with one of these options (sorted by ease of setting up)
   1. Clicking the use this template button on github, and cloning it locally
   2. Download this repo as a ZIP file using the github button (so it will not have any .git config) and extracting it
   3. Clone this repo locally and manually deleting the .git folder
      • Please note that you MUST delete the .git folder to use git yourself!!
   4. Forking this repo
      • Please note that you MUST create a new remote origin for this to work
2. Setup and customize this template by following the steps below

Basic commands

• Get started by installing dependencies
  • npm i
• Run in development mode
  • npm run serve
    • See the site on https://localhost:8080 instead of just http!!
• Lint source files with ESLint
  • npm run lint
• Preview production build locally
  • npm run preview
• Run type check
  • npm run typecheck
• Build for production deployment
  • npm run build
• Run type check before full production build
  • npm run build:full

Setup steps

Required

1. Set the package name and version in package.json
   • Remember to run npm i after this to get npm to update your package-lock.json file's name and version too
2. Update the title of your application in index.html
3. Update the favicon
4. Start creating your Vue SFCs in views/ and components/. You can reference the provided examples in the folders for how to create SFCs using the Composition API
5. Set the base URL of the API library in main.ts for your own API service if any
6. See Router module's README to learn how to register a new Route with a view component, and how to create auth protected routes.
   • By default all routes created will be public routes since there is no RouteGuard, see router's README on how to set it up.

Optional

1. Consider using the recommended development environment by following this
2. Create a .env file in your root directory to set environment variables
   • See https://vitejs.dev/guide/env-and-mode.html for reference on how to use .env files
   • Set VITE_API_URL to use as the API default base URL if you are not using the ternary method in main.ts
3. If you are using github pages to deploy and host your application, you need to update your vite config file
   1. You might need to set the production base URL path as your repo's name if your repo is not the default account/organisation repo.
      • See section on github-pages deployment for more details.
   2. You need to delete the base property used for demo purposes.
4. If you are not using github pages to deploy and host your application, you can delete the public/.nojekyll file so that it is not copied into your build output.
   • The file is there to make github pages deployments work, it is not required and can be left alone for almost all other deployment and hosting strategies.
   • See section on github-pages deployment for more details.
5. By default, the Bulma CSS library dependency will be bundled on build, if you prefer using a CDN to load Bulma instead, follow the instructions in main.ts and index.html to modify how Bulma is loaded.
6. Update vue router to use History mode instead in /src/router/Router.ts

Dependencies

• TypeScript as the language
• vue3
• vue-router
• pinia for state management
• pinia-plugin-persistedstate to persist state across sessions in localStorage
• bulma CSS library as the main styling dependency
• simpler-fetch as the API library

DevDependencies

• prettier
• eslint, this template is configured to follow the Vue.js style guide
• gh-pages is ran using npx when deploying to github pages, and so it will only be temporarily installed if deploying to github pages.

Technical details and notes

• Although Option API can still be used, it is not recommended, as the only advantage to it compared to Composition API is that it makes migration from vue2 easier. Since this template is designed to make it easier to start new projects, there is no point in supporting the older API whose TS support is not as good too.
• vue router is configured to use # hashed based routing rather than history mode
  • But this can be changed in /src/router/Router.ts
• Basic PWA support is enabled by default, see vite config for more details
• In development mode, vite is configured to use HTTPS by default as many use cases such as getting camera access require application to be loaded over HTTPS.

Recommended IDE Setup

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

Please make sure to disable Vetur when using this project in vs code, because with vetur installed, you will face these issues:

• Duplicated code intellisense provider, so for example when trying to use intellisense to jump to definition, it will not jump if there is more than 1 definition found, because both Volar and Vetur can find the definition.
• Vetur will error out when using composition API with a single <script setup> block, because it will not be able to understand the setup block and thus think that there is no default export when there is actually.

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 following these 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.

Reference: https://vuejs.org/guide/typescript/overview.html#takeover-mode

Deployment

Github Pages

To use Github Pages, ensure that the production base URL is set properly in your vite config file before building and deploying the site.

# Build the site and write build output to ./docs
# The default npm run build writes build output to ./dist
npm run build:gh-pages

# Deploys ./docs folder to github pages
npm run deploy:gh-pages

Github uses jekell to build and deploy your static site to github pages, and so, there are some filenames that are not allowed such as files that start with a period . or underscore _ which poses a problem as some build output files have underscore characters.

The solution to this is to ensure that a .nojekyll file is placed in the root of the build output directory, which for github pages is ./docs. However, since it is troublesome to always manually create the file after building, a .nojekyll file is placed in ./public so that it is automatically copied into the root of the build output directory on every build.

References:

• https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll
• https://github.community/t/unable-to-access-resources-in-folder-with-name-starting-with/10505

License & Author

Made available with MIT license, created by JJ