Getting Started

This guide will walk you through setting up your development environment and creating your first Vue 3 project using the Altersquare boilerplate.

Prerequisites

Before you begin, you'll need to install some tools and obtain the necessary access.

1. Node.js

Node.js is required to run the development server and build your project.

Check if Node.js is installed:

bash

node --version
# Expected output: v22.x.x or higher

Installation Options:

Option A: Using nvm (Recommended)

nvm (Node Version Manager) allows you to install and switch between multiple Node.js versions easily.

Step 1: Install nvm

Windows:

bash

# Download and run the nvm-windows installer from:
# https://github.com/coreybutler/nvm-windows/releases
# Download nvm-setup.exe and run it

# After installation, open a new terminal and verify:
nvm --version

macOS/Linux:

bash

# Install nvm using curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Or using wget
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Restart your terminal or run:
source ~/.bashrc   # for bash
source ~/.zshrc    # for zsh

# Verify installation
nvm --version

Step 2: Install Node.js using nvm

bash

# Install Node.js 22 (recommended)
nvm install 22

# Use Node.js 22
nvm use 22

# Set as default version
nvm alias default 22

# Verify installation
node --version
# Expected output: v22.x.x

Why Node 22?

Vue 3 and Vite work best with Node.js 22 (latest LTS). Older versions may cause compatibility issues with some dependencies.

Why use nvm?

nvm is recommended because it allows you to:

Install multiple Node.js versions side by side
Switch between versions for different projects
Avoid permission issues with global npm packages

2. npm (Node Package Manager)

npm comes bundled with Node.js. Verify it's installed:

bash

npm --version
# Expected output: 9.x.x or higher

Alternative Package Managers

You can also use yarn or pnpm if you prefer. Replace npm install with yarn or pnpm install in the commands below.

3. Git

Git is required to clone the boilerplate repository.

Check if Git is installed:

bash

git --version
# Expected output: git version 2.x.x

Installation:

Windows: Download from git-scm.com
macOS: brew install git or Xcode Command Line Tools
Linux: sudo apt install git (Ubuntu/Debian)

Configure Git Identity:

After installing Git, configure your identity (required for commits):

bash

# Set your name
git config --global user.name "Your Name"

# Set your email
git config --global user.email "your.email@company.com"

# Verify configuration
git config --global user.name
git config --global user.email

4. Code Editor

We recommend Visual Studio Code with the following extensions:

Extension	Purpose
Volar	Vue 3 language support
ESLint	Code linting
Prettier	Code formatting
SCSS IntelliSense	SCSS autocomplete

Disable Vetur

If you have Vetur installed (for Vue 2), disable it for Vue 3 projects. Volar is the official Vue 3 extension.

5. GitHub Access

You'll need access to the Altersquare GitHub organization:

Requesting Access:

Contact your Team Lead or Project Manager to request access. Provide the following information:

Your GitHub username
Which repositories you need access to (at minimum: vue3-boilerplate)

Step 1: Verify Access

Once access is granted, verify you can access the repository:

Method 1: Check via GitHub Web Interface

Go to github.com/altersquare/vue3-boilerplate
If you can see the repository (not a 404 error), you have access
Try clicking the Code button - you should see clone options

Method 2: Test Clone via Command Line

bash

# Try cloning the repository
git clone https://github.com/altersquare/vue3-boilerplate.git test-clone

# If successful, you'll see:
# Cloning into 'test-clone'...
# remote: Enumerating objects: 45, done.
# ...

# Clean up the test clone
cd ..
rm -rf test-clone  # or rmdir /s test-clone on Windows

Step 2: Configure Git Authentication

Using HTTPS (Recommended):

HTTPS is the simplest way to authenticate with GitHub. When you clone or push, Git will prompt you for your credentials.

First-time Setup:

bash

# Test authentication
git clone https://github.com/altersquare/vue3-boilerplate.git

What Happens on First Clone:

Git will prompt for your GitHub username
Git will prompt for your password (or Personal Access Token)
On Windows: Git Credential Manager will open a browser window for authentication
On macOS: Keychain will store your credentials
On Linux: Credentials will be stored in ~/.git-credentials

Where to Find Everything

Before you start, here's where to find all the resources you'll need:

📦 Repositories

Resource	Location	Description
Vue 3 Boilerplate	GitHub Repository	The starter template for new projects
Component Library	Components Documentation	Copy-paste Vue components and composables

📚 Documentation

Resource	Location	Description
Getting Started Guide	Getting Started	This guide - step-by-step setup instructions
Project Structure	Project Structure	Detailed explanation of all folders and files
Component Library Usage	Using Component Library	How to integrate components into your project
Composables	Composables Documentation	Available composables in the component library

🛠️ Tools & Utilities

Resource	Location	Description
Color Name Finder	Color Name Finder Tool	Utility to find color names from hex codes

📖 Guides & Workflows

Resource	Location	Description
Deployment Flow	Deployment Guide	How to deploy and upload assets to CDN

🔑 Access Requirements

Access Type	Where to Get It	Who to Contact
GitHub Organization Access	Request from team lead	Your project manager or team lead
API Base URL	From backend team	Backend/API team lead
Environment Variables	`.env` file in boilerplate	Check with project setup or team lead
Component Library Access	GitHub repository	Same as boilerplate access

📝 Quick Reference Links

Boilerplate Repository: GitHub - vue3-boilerplate
Component Library: Components Documentation
Node.js Download: nodejs.org
nvm Installation: nvm-windows (Windows) or nvm (macOS/Linux)
Git Download: git-scm.com
VS Code: code.visualstudio.com

Project Setup

Now that you have all prerequisites, let's set up your project.

Step 1: Clone the Boilerplate

bash

# Clone the repository
git clone https://github.com/altersquare/vue3-boilerplate.git my-project

Expected output:

Cloning into 'my-project'...
remote: Enumerating objects: 45, done.
remote: Counting objects: 100% (45/45), done.
remote: Compressing objects: 100% (32/32), done.
Receiving objects: 100% (45/45), 15.20 KiB | 2.17 MiB/s, done.
Resolving deltas: 100% (12/12), done.

Step 2: Navigate to the Project

bash

cd my-project

Step 3: Install Dependencies

bash

npm install

Expected output:

added 150 packages, and audited 151 packages in 12s

25 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

What this does:

Reads package.json to see all required dependencies
Downloads and installs all packages into node_modules/ folder
Creates package-lock.json to lock dependency versions
This may take 1-5 minutes depending on your internet speed

Verify installation:

bash

# Check if node_modules folder was created
ls node_modules  # macOS/Linux
dir node_modules  # Windows

# You should see many folders (vue, vite, pinia, etc.)

Step 4: Environment Configuration

Step 4.1: Locate the .env file

The .env file should be in the root of your project (same level as package.json):

bash

# Check if .env file exists
ls -la .env  # macOS/Linux
dir .env     # Windows

# If it doesn't exist, create it:
touch .env   # macOS/Linux
type nul > .env  # Windows

Step 4.2: Configure Environment Variables

Open the .env file in your code editor and add your configuration:

env

# API Configuration
VITE_API_BASE_URL=https://api.yourdomain.com

What to Configure:

Variable	Description	Example
`VITE_API_BASE_URL`	Base URL for your API endpoints	`https://api.yourdomain.com` or `http://localhost:3000`

For Local Development:

env

# Local development API
VITE_API_BASE_URL=http://localhost:3000

For Staging/Production:

env

# Staging API
VITE_API_BASE_URL=https://api-staging.yourdomain.com

# Production API
VITE_API_BASE_URL=https://api.yourdomain.com

Environment Variables

All environment variables must be prefixed with VITE_ to be accessible in your Vue code
Update the .env file with your project-specific values
Never commit sensitive data (API keys, secrets) to .env - use .env.local for secrets (git-ignored)

Step 4.3: Verify Environment Variables

Accessing environment variables in your code:

// In any Vue file or JavaScript module
const apiUrl = import.meta.env.VITE_API_BASE_URL;
console.log("API URL:", apiUrl);

// In network/appAxios.js (if configured)
const baseURL = import.meta.env.VITE_API_BASE_URL;

Test that variables are loaded:

bash

# Restart dev server after changing .env
npm run dev

Then check the browser console - you should see your API URL logged.

Step 4.4: Environment-Specific Files (Optional)

You can create environment-specific files:

.env - Default values (committed to git)
.env.local - Local overrides (git-ignored, for secrets)
.env.development - Development environment
.env.production - Production environment

Vite automatically loads the appropriate file based on the mode.

Step 5: Run the Development Server

bash

npm run dev

Expected output:

  VITE v5.x.x  ready in 500 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.1.100:5173/
  ➜  press h + enter to show help

🎉 Congratulations! Open http://localhost:5173 in your browser to see your app.

Step 5.1: Verify the Application is Running

Open your browser and navigate to http://localhost:5173
You should see:
- The Vue 3 application homepage
- No console errors (check browser DevTools)
- Hot Module Replacement (HMR) working - try editing a file and see it update automatically

Step 5.2: Test Hot Module Replacement (HMR)

Open src/views/HomeWrapper.vue (or any Vue file)
Make a small change (e.g., change some text)
Save the file
The browser should automatically update without a full page refresh

Step 5.3: Check Browser Console

Open browser DevTools (F12) and check:

Console tab - Should have no errors
Network tab - Should show successful requests
Vue DevTools (if installed) - Should show Vue component tree

Step 5.4: Verify Project Structure

bash

# Check that all key folders exist
ls src/assets      # Should show scss/, images/, getAssets.js
ls src/components  # Should show component folders
ls src/composable  # Should show composable files
ls src/stores      # Should show store files
ls src/views       # Should show view files

If something doesn't work:

Check terminal for errors - Look for red error messages
Check browser console - Press F12 and look at Console tab
Verify Node.js version - Run node --version (should be 22.x)

Clear cache and reinstall:

bash

rm -rf node_modules package-lock.json  # macOS/Linux
rmdir /s node_modules & del package-lock.json  # Windows
npm install

Step 6: Build for Production

When you're ready to deploy:

bash

# Create a production build
npm run build

Expected output:

vite v5.x.x building for production...
✓ 45 modules transformed.
dist/index.html                  0.45 kB │ gzip:  0.29 kB
dist/assets/index-DiwrgTda.css   5.20 kB │ gzip:  1.45 kB
dist/assets/index-CdGHgJpr.js   85.32 kB │ gzip: 27.15 kB
✓ built in 2.50s

Preview the production build locally:

bash

npm run preview

Integrating the Component Library

The Altersquare component library provides ready-to-use Vue 3 components that you can copy directly into your boilerplate project. This section explains how to find, copy, and use components from the library.

Step 1: Access the Component Library

Where to Find Components:

Component Library Documentation:
- URL: Component Library Docs
- Location: Browse all available components with examples and API documentation
Deployed Component Library:
- URL: https://vue-library.coolify.orderstack.dev/components/
- Purpose: Interactive demos and live examples of all components (always available at this URL)
Component Library Repository:
- GitHub: altersquare-vue-ui-component-lib
- Purpose: Source code for all components

Step 2: Browse Available Components

Component Categories:

Category	Components	Use Case
Form Components	Input, TextArea, Checkbox, Radio, DatePicker, Dropdown, FileInput, Switch, Slider, Range	Building forms and collecting user input
UI Components	Accordion, Tabs, BreadCrumb, Snackbar, Pagination, Chip	Displaying content and navigation
Progress Components	Loader, LinearProgress, CircularProgress	Showing loading states
Navigation Components	HorizontalAppBar, VerticalAppBar	App navigation and headers
Base Components	Menu, Table, ScrollObserver, Toast, PopOver, Tooltip	Core UI elements

View All Components:

Go to Component Library Documentation to see the full list

Step 3: Copy a Component to Your Project

Example: Adding an Input Component

Step 3.1: Find the Component Code

Navigate to Input Component Documentation
Click on the Code tab or view the source code
Copy the entire component code

Step 3.2: Create Component File in Your Project

bash

# Navigate to your project's components folder
cd src/components

# Create a folder for shared components (if it doesn't exist)
mkdir -p sharedComponents  # macOS/Linux
mkdir sharedComponents     # Windows

# Create the component file
touch sharedComponents/OInput.vue  # macOS/Linux
type nul > sharedComponents\OInput.vue  # Windows

Step 3.3: Paste Component Code

Open src/components/sharedComponents/OInput.vue in your editor
Paste the component code you copied from the library
Save the file

Step 3.4: Verify Component Structure

Your component file should look like:

vue

<template>
  <!-- Component template -->
</template>

<script setup>
// Component logic
</script>

<style lang="scss" scoped>
// Component styles
</style>

Step 4: Use the Component in Your Project

Step 4.1: Import the Component

In any Vue file where you want to use the component:

vue

<script setup>
import OInput from "@/components/sharedComponents/OInput.vue";
</script>

Step 4.2: Use in Template

vue

<template>
  <div>
    <OInput
      v-model="email"
      label="Email Address"
      type="email"
      placeholder="Enter your email"
    />
  </div>
</template>

<script setup>
import { ref } from "vue";
import OInput from "@/components/sharedComponents/OInput.vue";

const email = ref("");
</script>

Step 5: Copy Composables from the Library

Step 5.1: Find Composable Code

Navigate to Composables Documentation
Or browse the composables in the component library repository
Copy the composable code

Step 5.2: Add to Your Project

bash

# Navigate to composable folder
cd src/composable

# Create the composable file
touch useToastComposable.js  # macOS/Linux
type nul > useToastComposable.js  # Windows

Step 5.3: Paste and Use

Paste the composable code into the file
Import and use in your components:

vue

<script setup>
import { useToast } from "@/composable/useToastComposable";

const toast = useToast();

const showSuccess = () => {
  toast.success("Operation completed!");
};
</script>

Step 6: Organize Your Components

Recommended Folder Structure:

src/components/
├── sharedComponents/          # Components from library
│   ├── OInput.vue
│   ├── OButton.vue
│   ├── OToast.vue
│   ├── OSnackbar.vue
│   └── OPopup.vue
└── [FeatureName]/             # Feature-specific components
    └── [ComponentName].vue

Naming Convention:

Library components: Keep original names (e.g., OInput.vue, OToast.vue)
Your custom components: Use descriptive names (e.g., UserProfileCard.vue, ProductList.vue)

Step 7: Verify Component Works

Test Your Component:

Start dev server (if not running):
bash
```
npm run dev
```

Create a test page or modify an existing view:

vue

<!-- src/views/TestComponentsWrapper.vue -->
<template>
  <div class="test-page">
    <h1>Testing Components</h1>
    <OInput v-model="testValue" label="Test Input" />
    <button @click="showToast">Test Toast</button>
  </div>
</template>

<script setup>
import { ref } from "vue";
import OInput from "@/components/sharedComponents/OInput.vue";
import { useToast } from "@/composable/useToastComposable";

const testValue = ref("");
const toast = useToast();

const showToast = () => {
  toast.success("Component is working!");
};
</script>

Add route (if needed):

// src/router/index.js
{
  path: '/test-components',
  name: 'TestComponents',
  component: () => import('@/views/TestComponentsWrapper.vue')
}

Visit the page in your browser and test the component

Step 8: Customize Components (Optional)

Since you have the source code, you can customize components:

Option 1: Modify Directly

Open the component file (e.g., OInput.vue)
Modify styles, props, or logic as needed
Save and see changes immediately (HMR)

Option 2: Extend Component

Create a wrapper component:

vue

<!-- src/components/sharedComponents/CustomInput.vue -->
<template>
  <OInput v-bind="$attrs" :class="['custom-input', $attrs.class]" />
</template>

<script setup>
import OInput from "./OInput.vue";
</script>

<style lang="scss" scoped>
.custom-input {
  // Your custom styles
}
</style>

Best Practices

Copy only what you need - Don't copy all components at once, add them as needed
Keep library components separate - Use sharedComponents/ folder for library components
Document customizations - If you modify a library component, document the changes
Update components - Periodically check library for updates and improvements
Use composables correctly - Always mount required components for composables to work

📖 Related Documentation:

Using Component Library → - Detailed guide on component integration
Component Library Documentation → - Browse all available components

Common Commands Reference

Command	Description
`npm run dev`	Start development server with hot reload
`npm run build`	Create production build in `dist/`
`npm run preview`	Preview production build locally
`npm run lint`	Run ESLint to check code quality
`npm run lint:fix`	Auto-fix linting issues

Need more help? Check the Guides section or reach out to your team lead.

Getting Started ​

Prerequisites ​

1. Node.js ​

Option A: Using nvm (Recommended) ​

2. npm (Node Package Manager) ​

3. Git ​

4. Code Editor ​

5. GitHub Access ​

Step 1: Verify Access ​

Step 2: Configure Git Authentication ​

Where to Find Everything ​

📦 Repositories ​

📚 Documentation ​

🛠️ Tools & Utilities ​

📖 Guides & Workflows ​

🔑 Access Requirements ​

📝 Quick Reference Links ​

Project Setup ​

Step 1: Clone the Boilerplate ​

Step 2: Navigate to the Project ​

Step 3: Install Dependencies ​

Step 4: Environment Configuration ​

Step 5: Run the Development Server ​

Step 6: Build for Production ​

Integrating the Component Library ​

Step 1: Access the Component Library ​

Step 2: Browse Available Components ​

Step 3: Copy a Component to Your Project ​

Step 4: Use the Component in Your Project ​

Step 5: Copy Composables from the Library ​

Step 6: Organize Your Components ​

Step 7: Verify Component Works ​

Step 8: Customize Components (Optional) ​

Best Practices ​

Common Commands Reference ​

Getting Started

Prerequisites

1. Node.js

Option A: Using nvm (Recommended)

2. npm (Node Package Manager)

3. Git

4. Code Editor

5. GitHub Access

Step 1: Verify Access

Step 2: Configure Git Authentication

Where to Find Everything

📦 Repositories

📚 Documentation

🛠️ Tools & Utilities

📖 Guides & Workflows

🔑 Access Requirements

📝 Quick Reference Links

Project Setup

Step 1: Clone the Boilerplate

Step 2: Navigate to the Project

Step 3: Install Dependencies

Step 4: Environment Configuration

Step 5: Run the Development Server

Step 6: Build for Production

Integrating the Component Library

Step 1: Access the Component Library

Step 2: Browse Available Components

Step 3: Copy a Component to Your Project

Step 4: Use the Component in Your Project

Step 5: Copy Composables from the Library

Step 6: Organize Your Components

Step 7: Verify Component Works

Step 8: Customize Components (Optional)

Best Practices

Common Commands Reference