repository·main·Indexed 22 days ago
https://github.com/element-plus/element-plus-vite-starterA starter kit for building Vue applications using Element Plus and Vite. It features on-demand component loading via unplugin-vue-components, Static Site Generation (SSG) with vite-ssg, utility-first styling with UnoCSS, and type-safe routing via unplugin-vue-router. The project includes a convention-based module system for plugin installation and a pre-configured ESLint setup using @antfu/eslint-config.
This starter kit uses unplugin-vue-components to enable on-demand importing of Element Plus components. This approach ensures that only the components you actually use are bundled, reducing the final bundle size.
If you prefer to import all components manually, you can follow the standard Element Plus Quickstart guide.
To set up the project, clone the repository and install dependencies using your preferred package manager. The project supports pnpm, npm, and yarn.
git clone https://github.com/element-plus/element-plus-vite-starter
cd element-plus-vite-starter
pnpm install
# Or using npm
npm install
# Or using yarn
yarn installTo compile the project and enable hot-reloading for development, use the dev script.
npm run devTo compile and minify the project for production deployment, use the build script.
npm run buildThe project implements a convention-based module system. Any file located in the ./modules/ directory that exports an install function conforming to the UserModule type will be automatically loaded and executed during the application initialization phase.
This allows you to encapsulate plugin installations (like Pinia, Vue Router, or Element Plus) into separate, manageable files.
// Inside the ViteSSG callback in src/main.ts:
Object.values(import.meta.glob<{ install: UserModule }>('./modules/*.ts', { eager: true }))
.forEach(i => i.install?.(ctx))src/styles/element/index.scss.This project uses unplugin-vue-router to automatically generate type definitions for your application's routes. The file src/typed-router.d.ts is a machine-generated file that provides a RouteNamedMap interface. This interface allows for type-safe route navigation and parameter handling by mapping path strings to their corresponding RouteRecordInfo types.
Important Notes:
tsconfig.json under the includes or files array so TypeScript can resolve the generated types.To use Element Plus components that rely on specific SCSS variables or styles (like ElMessage or MessageBox), you must import the corresponding theme-chalk SCSS files.
Available style imports in this project include:
element-plus/theme-chalk/src/message.scss (for ElMessage)element-plus/theme-chalk/src/message-box.scss (for MessageBox)element-plus/theme-chalk/src/overlay.scss (for modal overlays)Alternatively, you can use the pre-compiled CSS by importing element-plus/dist/index.css.
// For specific component styles:
import 'element-plus/theme-chalk/src/message.scss'
import 'element-plus/theme-chalk/src/message-box.scss'
import 'element-plus/theme-chalk/src/overlay.scss'
// Or for all Element Plus CSS:
// import "element-plus/dist/index.css";The project uses vite-ssg for Static Site Generation (SSG). Instead of the standard Vue createApp, you must export a createApp function generated by ViteSSG. This function takes the root App component, a configuration object containing routes and base URL, and an initialization callback (ctx) where you can install plugins and modules.
To add custom functionality, place TypeScript files in the modules/ directory. The entrypoint automatically discovers and executes the install method of any module found there.
import { ViteSSG } from 'vite-ssg'
import { routes } from 'vue-router/auto-routes'
import App from './App.vue'
export const createApp = ViteSSG(
App,
{
routes,
base: import.meta.env.BASE_URL,
},
(ctx) => {
// Modules in ./modules/*.ts are automatically installed here
Object.values(import.meta.glob<{ install: UserModule }>('./modules/*.ts', { eager: true }))
.forEach(i => i.install?.(ctx))
},
)The project uses UnoCSS for utility-first CSS. The configuration is defined in uno.config.ts using defineConfig. It includes several presets for Uno, Attributify, Icons, Typography, and Web Fonts, along with transformers for directives and variant groups. You can also define custom shortcuts to group utility classes into reusable names.
import {
defineConfig,
presetAttributify,
presetIcons,
presetTypography,
presetUno,
presetWebFonts,
transformerDirectives,
transformerVariantGroup,
} from 'unocss'
export default defineConfig({
shortcuts: [
['btn', 'px-4 py-1 rounded inline-block bg-teal-700 text-white cursor-pointer !outline-none hover:bg-teal-800 disabled:cursor-default disabled:bg-gray-600 disabled:opacity-50'],
['icon-btn', 'inline-block cursor-pointer select-none opacity-75 transition duration-200 ease-in-out hover:opacity-100 hover:text-teal-600'],
],
presets: [
presetUno(),
presetAttributify(),
presetIcons({
scale: 1.2,
}),
presetTypography(),
presetWebFonts({
fonts: {
sans: 'DM Sans',
serif: 'DM Serif Display',
mono: 'DM Mono',
},
}),
],
transformers: [
transformerDirectives(),
transformerVariantGroup(),
],
safelist: 'prose prose-sm m-auto text-left'.split(' '),
})This project uses @antfu/eslint-config for linting and formatting. You can customize the linting behavior by passing an options object to the antfu() function in eslint.config.js.
Available configuration options in this starter:
formatters: Enables code formatting via ESLint.unocss: Enables support for UnoCSS rules.vue: Enables support for Vue SFC (Single File Component) linting.import antfu from '@antfu/eslint-config'
export default antfu({
formatters: true,
unocss: true,
vue: true,
})The project provides two exported constants to manage dark mode state using @vueuse/core utilities.
isDark: A reactive state that tracks whether dark mode is currently active.toggleDark: A function that toggles the isDark state between true and false.You can import these directly into your Vue components to reactively update your UI or to create a theme switcher button.