DOCSEARCHbyAlgolia
Submit Docs

vue3-vant-mobile

repository·main·Indexed 24 days ago

https://github.com/vue-zone/vue3-vant-mobile

A high-performance mobile web application template based on the Vue 3 ecosystem, featuring Vite 8, TypeScript, and the Vant UI library. It includes pre-configured tools for file-based routing via unplugin-vue-router, state management with Pinia, atomic CSS using UnoCSS, and PWA support. The template provides developer experience enhancements such as component auto-importing, i18n support, and a mock server via vite-plugin-mock-dev-server.

Tokens
5.6K
Snippets
15
Records
38
Agent score
84%

What's inside vue3-vant-mobile

  1. Overview of vue3-vant-mobile features

    main

    vue3-vant-mobile

    An mobile web apps template based on the Vue 3 ecosystem designed to accelerate business development.

    Core Tech Stack:

    • Frameworks: Vue 3, Vite 8, Pinia (State Management), Vue Router.
    • UI & Styling: Vant (Mobile UI components), UnoCSS (Atomic CSS), viewport vw/vh layout.
    • Developer Experience: TypeScript, <script setup> syntax, API auto-import (unplugin-auto-import), component auto-loading (unplugin-vue-components), vConsole for mobile debugging.
    • Capabilities: PWA support, I18n (Internationalization), Local data mocking (vite-plugin-mock-dev-server), Dark mode support, and ESM by default.
    • Deployment: Zero-config deployment via Netlify.

  2. Overview of vue3-vant-mobile features and stack

    main

    vue3-vant-mobile is a mobile web application template built on the Vue 3 ecosystem. Key features include:

    • Core: Vue 3, Vite 8, TypeScript, and ESM by default.
    • Routing & State: File-based routing and Pinia for state management (with pinia-plugin-persistedstate for persistence).
    • Styling: UnoCSS (atomic CSS) and mobile-first viewport adaptation using postcss-mobile-forever.
    • UI Library: Vant (mobile UI) including vant-touch-emulator for desktop testing and vant-use for composition APIs.
    • Developer Experience:
      • Auto-importing for components and APIs (Vue Composition API, etc.).
      • Mock server support via vite-plugin-mock-dev-server.
      • vConsole for mobile debugging.
      • PWA support via vite-plugin-pwa.
      • I18n support via vue-i18n and unplugin-vue-i18n.
    • Deployment: Zero-config deployment on Netlify.

  4. Post-setup checklist for new projects

    main

    After initializing a project from this template, ensure you update the following to make it your own:

    • Update the author name in LICENSE.
    • Change the title in index.html.
    • Update the hostname in vite.config.ts.
    • Replace the favicon in the public directory.
    • Clean up the README and remove default routes.

  5. Configure your new project from the template

    main

    After cloning the template, follow this checklist to personalize your application:

    • Change the author name in LICENSE.
    • Change the title in index.html.
    • Change the hostname in vite.config.ts.
    • Change the favicon in public.
    • Clean up the READMEs and remove unused routes.

  6. Define route names and meta information using SFC `<route>` custom blocks

    main
    To define the route name and metadata (such as transition animations) for a specific page, use the SFC <route> custom block. This approach allows you to control route-specific behaviors, like transition animations, directly within the component file. This feature relies on the unplugin-vue-router mechanism for extending routes via custom blocks.

  7. Use file-based routing with src/pages

    main

    The project uses file-based routing to automatically generate routes based on the structure of your Vue files located in the src/pages directory. The generated route paths will mirror the file structure within that directory.

    This mechanism is powered by unplugin-vue-router. For advanced configuration or detailed behavior, refer to the unplugin-vue-router documentation.

  8. Save and restore scroll position for a specific container

    main

    If you are scrolling a specific element (e.g., a div with overflow: auto) rather than the entire window, follow these steps:

    1. Assign a ref: Add a ref attribute to the scrolling element in your template.
    2. Declare the ref: Create a corresponding ref in your setup function.
    3. Capture position on leave: In onBeforeRouteLeave, set your stored position variable to the container's scrollTop property.
    4. Apply position on activation: In onActivated, set the container's scrollTop property to the stored value.
    <!-- 1. Add ref to the template -->
<div ref="scrollContainer" class="...">...</div>
    // 2. Declare the reference in setup
const scrollContainer = ref(null)
const scrollTop = ref(0)

// 3. Save position in onBeforeRouteLeave
onBeforeRouteLeave(() => {
  if (scrollContainer.value) {
    scrollTop.value = scrollContainer.value.scrollTop
  }
})

// 4. Restore position in onActivated
onActivated(() => {
  if (scrollContainer.value) {
    scrollContainer.value.scrollTop = scrollTop.value
  }
})

  10. Clone vue3-vant-mobile template locally

    main

    To start a new project using this template with a clean git history, use pnpm dlx tiged.

    Prerequisites:

    • Node.js version 22.22.0+ required.
    • pnpm installed (if not installed, run npm install -g pnpm).

    Steps:

    1. Clone and initialize the template.
    2. Navigate to the project directory.
    3. Install dependencies.
    pnpm dlx tiged vue-zone/vue3-vant-mobile my-mobile-app
cd my-mobile-app
pnpm i

  11. How to save and restore page scroll position

    main

    To preserve the scroll position when navigating away from a page and returning to it, you must use a combination of Vue's keepAlive component, the onBeforeRouteLeave hook to capture the position, and the onActivated hook to restore it.

    Basic Workflow

    1. Enable Caching: Wrap your component in <keep-alive> or set keepAlive: true in your router configuration to ensure the component instance is not destroyed.
    2. Capture Position: Use onBeforeRouteLeave to save the current window.scrollY (or fallback values) into a reactive variable.
    3. Restore Position: Use onActivated to trigger window.scrollTo using the saved value.
    // Define a ref to store the scroll position
const scrollTop = ref(0)

// When a component with keepAlive set to true is activated, scroll to the saved position
onActivated(() => {
  window.scrollTo(0, scrollTop.value)
})

// Before leaving the route, save the current scroll position
onBeforeRouteLeave(() => {
  scrollTop.value
    = window.scrollY
      || document.documentElement.scrollTop
      || document.body.scrollTop
})