npm package: @manderley/vike-vue-vuetify
Description: A reusable Vike extension that provides a clean, SSR-safe Vuetify 3 integration for Vike + Vue projects. This package removes the need for manual Vuetify setup, SSR wiring, and duplicated boilerplate by centralizing everything into a single Vike extensio
Latest version: 0.1.3


# vike-vue-vuetify 💛💚
A reusable Vike extension that provides a clean, SSR-safe Vuetify 3 integration for Vike + Vue projects.
This package removes the need for manual Vuetify setup, SSR wiring, and duplicated boilerplate by centralizing everything into a single Vike extension.

---

## 📑 Menu

- [Features](#-features)
- [Installation](#-installation)
- [Usage](#usage-consumer-project)
- [Architecture](#-how-it-works-architecture)
- [Why an Extension?](#-why-an-extension)
- [Full & Simple Example](#-full--simple-example)
- [Contributing](#-contributing)

---
## ✨ Features

- ✅ Vuetify 3 integration for **Vike + Vue**
- ✅ Full **SSR support**
- ✅ Automatic Vuetify app injection
- ✅ Extensible configuration via hooks
- ✅ Custom themes & overrides support
- ✅ Clean separation between app code and framework setup
- ✅ Reusable across multiple projects
---

  

## 📦 Installation

  

```bash
npm  install  @manderley/vike-vue-vuetify  vuetify  vite-plugin-vuetify
```

  

Peer dependencies:

  

-  `vike`
-  `vike-vue`
-  `vue`
-  `vuetify`
- `vite-plugin-vuetify`

  

---

  

## Usage (Consumer Project)

> ⚠ if you want see full and simole example see this [repo](https://github.com/Mahdi-heydari/vike-vue-vuetify-example).


  

### 1. Add the extension config to Vike

  

In your project’s `+config.ts` (or equivalent):
```typescript
import  vikeVue  from  "vike-vue/config";
import  vuetify  from  "@manderley/vike-vue-vuetify/config";

export  default {
extends: [vikeVue, vuetify],
};

```

  

#### 1.1 🎨 Custom Vuetify Configuration <a id="custom-vuetify-config"></a>

  

This extension exposes an `onCreateVuetify` hook that allows consumer projects to customize the Vuetify instance after it is created.

Example: Custom Theme
```typescript
vuetify: {
	theme: {
		defaultTheme: "dark",
	},
},
```

  

You can read more about it:
- [Define custom themes](https://vuetifyjs.com/en/features/theme/)

### 2. Configure Vite (Important for SSR)

  

Vuetify imports CSS internally, so Vite must handle it during SSR.

> ⚠ important
> In Vite, when you use SSR, Vite by default considers most `node_modules`
> packages as external. That is, these packages are not bundled and are
> handed over to Node.js to load them as is. But sometimes it is
> necessary to bundle one or more packages into the SSR output package
> instead of being external — for example, when those packages are not
> ESM modules, or require a special transformation. This is where
> ssr.noExternal comes into play.
> 
> In our case, styles and components were the problem.. because each
> component has its own style and in SSR these styles were handed over
> to Node and caused an error.. So this is a very necessary step.
> Related article link: 
> [ssr.noExternal](https://vite.dev/config/ssr-options#ssr-noexternal)

  

```typescript
// vite.config.ts

import { defineConfig } from  "vite";
import  vue  from  "@vitejs/plugin-vue";
import  vike  from  "vike/plugin";
import  vuetify  from  "vite-plugin-vuetify";

export  default  defineConfig({
	plugins: [vue(), vike(), vuetify({ autoImport: true })],
	ssr: {
		noExternal: ["vuetify", "@manderley/vike-vue-vuetify"],
	},
});
```

### 3. Register styles and icons (+Head.vue)
```typescript
import  "@mdi/font/css/materialdesignicons.css";
import  "vuetify/styles";
```
  

### 4. Run the project
```bash
npm  run  dev
```

That’s it. ✅
No manual Vuetify setup is required.

  
  

---
## 🧠 How It Works (Architecture)
This extension relies on Vike lifecycle hooks to initialize Vuetify correctly for both client and server environments.
### 📁 File Structure

```text
src/
├─ +config.ts
└─ integration/
   ├─ createVuetifyPlus.ts
   ├─ +onCreateApp.ts
   └─ +onCreatePageContext.ssr.ts

```

### +config.ts : 
Registers the extension with Vike and declares lifecycle hooks.
Key responsibilities:
-   Defines the extension name
-    Registers `onCreateApp` and `onCreatePageContext`
- Exposes extension metadata (`onCreateVuetify`)


### createVuetifyPlus.ts :
Central Vuetify factory.
Key responsibilities:

 - Creates the Vuetify instance
 - Registers components and directives
 - Stores Vuetify in the page or global context
 - Executes all `onCreateVuetify` hooks

### +onCreatePageContext.ssr.ts :
Runs during SSR.
Key responsibilities:
manages `createVuetifyPlus` and pass the `pageContext` as argument

---
## 🧩 Why an Extension?
Instead of duplicating Vuetify setup in every project:
-   ❌ Manual `createVuetify`
-   ❌ Multiple setup files
-   ❌ Hard-to-maintain configuration

This extension provides:

-   ✅ Centralized integration
-   ✅ Cleaner app code
-   ✅ Better reusability
-   ✅ Lower maintenance cost


---
## 🚀 Full & Simple Example

Want to see this extension in action with a **real Vike + Vue + Vuetify project**?

👉 Check out the complete example repository:

### 🔗 vike-vue-vuetify-example  
https://github.com/Mahdi-heydari/vike-vue-vuetify-example

### What you’ll find there:
- ✅ Minimal and clean project structure
- ✅ Full SSR setup with Vike
- ✅ Vuetify working out of the box
- ✅ Proper Vite + SSR configuration
- ✅ No manual Vuetify wiring at all

If you’re unsure about any step in the setup,  
**this example is the fastest way to understand how everything fits together.**

---
## 🤝 Contributing

Contributions are very welcome!  
This project is still evolving, and there are many ways you can help improve it.

### You can contribute by:
- 🐛 Reporting bugs or edge cases
- 💡 Suggesting improvements or new features
- 🧩 Improving documentation or examples
- 🔧 Submitting pull requests

### How to get started:
1. Fork the repository
2. Create a new branch (`feature/your-feature-name`)
3. Make your changes
4. Open a pull request with a clear description

Even small contributions matter —  
whether it’s fixing a typo, improving docs, or sharing ideas.

If you’re using this extension in your project,  
**your feedback is especially valuable.**

---
## 🙏 Special Thanks

A special thanks to **Mahdi Gholamrezaei**  
👉 https://github.com/mrmmg

For sharing valuable insights and providing the right mental direction on how to approach this integration properly.
The discussions and guidance helped shape the overall architecture and decision-making process behind this extension.