ymap-frontend

A Vue 3 + Vite frontend scaffold tailored for fast development using Bun as the runtime/package manager. This README expands on the minimal template instructions with detailed guidance for installation, development, build, testing, environment variables, deployment, and common troubleshooting.

I wrote this to help you get started quickly and to document conventions I recommend for this project.

---

Table of contents

• Project overview
• Prerequisites
• Installation
• Development
• Available scripts
• Environment variables
• Project structure
• Linting, formatting & type checking
• Testing
• Building & previewing production bundles
• Deployment recommendations
• Debugging & troubleshooting
• Contributing
• License & contact

---

Project overview You have a modern Vue 3 single page application built with Vite. It uses the speed of Bun for install and scripts. The repo follows a typical Vite + Vue layout: src/ contains application code, public/ static assets, and index.html is the app entry.

This README assumes:

• Vue 3 (Composition API)
• Vite as the bundler/dev server
• Bun as package manager / script runner (commands like bun install, bun dev, bun run build)

If you need the project to run with npm/yarn instead of bun, substitute commands accordingly.

Prerequisites

• Bun (v1.x or higher recommended). Install from https://bun.sh
• Node-compatible tooling if you plan to use other package managers
• A modern browser (Chrome/Edge/Firefox) for development with Vue devtools

Installation

1. Clone the repo:

git clone <repository-url>
cd ymap-frontend

2. Install dependencies with Bun:

bun install

Development Start the dev server (Vite):

bun dev

• The dev server supports hot module replacement (HMR).
• Open the URL printed by Vite (usually http://localhost:5173) in your browser.
• Use Vue Devtools in Chrome/Firefox for component inspection.

Available scripts These are the standard commands included in the template. Run them with bun (e.g., bun run build) or adapt to npm/yarn as needed.

• bun dev — Start the Vite dev server with HMR.
• bun run build — Produce an optimized production build in dist/.
• bun run preview — (If configured) serve built output locally for testing.
• bun lint — Run ESLint checks (if ESLint is configured).
• bun test — Run tests (if a test runner is configured, e.g. Vitest or Jest).

Example usage:

# Start dev server
bun dev

# Build for production
bun run build

# Lint code
bun lint

Environment variables Use a .env file for local environment variables. Vite supports import.meta.env for access at runtime. Keep these rules:

• Prefix any variable that should be exposed to the client with VITE_ (e.g. VITE_API_BASE_URL).
• Do not commit secrets (.env.local or .env should be in .gitignore).

Example .env (do not commit):

VITE_API_BASE_URL=https://api.example.com
VITE_MAP_API_KEY=your_map_service_key_here

Accessing in code:

• Use import.meta.env.VITE_API_BASE_URL inside your Vue components or other client code.

Project structure A recommended structure for the repo:

• index.html - Vite entry HTML
• public/ - Static assets
• src/
  • main.ts - App bootstrap
  • App.vue - Root component
  • components/ - Reusable Vue components
  • views/ - Page-level components
  • router/ - Vue Router configuration
  • store/ or composables/ - State management or composables (Pinia / Vuex)
  • assets/ - Images/CSS
  • types/ - Global TypeScript types
• vite.config.ts - Vite configuration
• tsconfig.json - TypeScript configuration
• .eslintrc / .prettierrc - Lint/format config

Example paths you’ll commonly edit:

• src/main.ts
• src/App.vue
• src/components/YourComponent.vue

Linting, formatting & type checking

• ESLint and Prettier are recommended to keep code consistent.
• The template uses vue-tsc to provide type checking for .vue files when using TypeScript.
• Recommended editor setup:
  • VS Code with the Volar extension (disable Vetur)
  • Prettier and ESLint extensions

Type-checking:

# Run TypeScript type checks (via vue-tsc if configured)
bun run typecheck

Testing If tests are set up (Vitest is a common choice in Vite projects), run:

bun run test

If tests are not yet configured, consider adding Vitest for fast unit testing with Vite compatibility.

Building & previewing production bundles Build:

bun run build

The production bundle will be written to dist/ by default.

Preview:

bun run preview

Preview runs a local static server to verify the production bundle before deployment (this may require a preview script in package.json that uses vite preview).

Deployment recommendations You can deploy the dist/ output to most static hosting services:

• Vercel: automatic deployment from Git with a Vite build step.
• Netlify: set build command to bun run build and publish directory to dist.
• GitHub Pages: push dist/ to gh-pages branch or leverage GH Actions.
• Docker: You can create a small static server image to serve dist/ (example below).

Example Dockerfile (simple static server using nginx):

# Build stage
FROM node:18-alpine AS builder
WORKDIR /app
COPY . .
# If using Bun, you might need a Bun-enabled builder image. Using npm/yarn is more portable here:
RUN npm ci
RUN npm run build

# Serve stage
FROM nginx:stable-alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

CI/CD tips

• Cache Bun or node_modules between runs for faster CI.
• Run bun lint and bun run test in CI before building.
• Publish artifacts (e.g., dist/) or deploy directly from CI to your hosting provider.

Debugging & troubleshooting

• If HMR doesn't reflect changes: clear the browser cache and restart bun dev.
• If environment variables aren't available: ensure they are prefixed with VITE_ and restart the dev server after changing .env.
• Type errors in .vue files: make sure vue-tsc is configured and your IDE uses Volar.

Common debugging commands:

# Install dependencies
bun install

# Development
bun dev

# Build production
bun run build

# Preview production build (if configured)
bun run preview

# Lint
bun lint

# Test
bun run test