New Tab Router


A Vue 3 + Vue Router 4 package that adds intelligent navigation behavior, specifically Cmd/Ctrl+click functionality to programmatic router.push() calls.

✨ Features

- 🎯 Smart Navigation: Automatically detects Cmd/Ctrl key presses during router.push() calls
- 🆕 New Tab Support: Opens routes in new tabs when modifier keys are pressed
- 🔧 Highly Configurable: Custom behaviors, callbacks, and route patterns
- 📱 Cross-Platform: Works on macOS (Cmd), Windows/Linux (Ctrl)
- 🛡️ Type Safe: Full TypeScript support with comprehensive type definitions
- 🚀 Zero Breaking Changes: Non-intrusive addition of new tab functionality to existing router
- 📦 Tree Shakeable: Optimized bundle size with ESM support
- 🧪 Well Tested: Comprehensive test coverage with Vitest and Playwright

🚀 Quick Start

$3

``bash
npm install vue-router-newtab


or

yarn add vue-router-newtab

or

pnpm add vue-router-newtab
`

$3

`typescript
import { createRouter, createWebHistory } from 'vue-router';
import { newTabRouter } from 'vue-router-newtab';

const router = createRouter({
history: createWebHistory(),
routes: [
{ path: '/', component: Home },
{ path: '/about', component: About },
{ path: '/contact', component: Contact },
],
});

// Enhance the router with Cmd/Ctrl+click support
newTabRouter(router);

// Now your existing router.push() calls work intelligently!
// Cmd/Ctrl + router.push('/about') = opens in new tab
// Normal router.push('/about') = normal navigation
`

$3

If you're using unplugin-vue-router for file-based routing, you need to import the type declarations in your main setup file:

`typescript
// main.ts or router setup file
import 'vue-router-newtab/unplugin-vue-router.d.ts';
import { createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import { newTabRouter } from 'vue-router-newtab';

// Your router setup with unplugin-vue-router
const router = createRouter({
history: createWebHistory(),
routes: [], // Routes are auto-generated by unplugin-vue-router
});

// Enhance the router with Cmd/Ctrl+click support
newTabRouter(router);
`

This import ensures that TypeScript recognizes the enhanced router.push() method with the additional options when using unplugin-vue-router's typed routing.

$3

`vue



`

📖 API Reference

$3

Adds new tab functionality to a Vue Router instance with intelligent navigation behavior.

Parameters:

- router: Router - The Vue Router instance to support newTab behaviour
- config?: NewTabRouterConfig - Optional configuration object

Returns: NewTabRouter - The router instance with new tab functionality

$3

`typescript
interface NewTabRouterConfig {
/* Enable Cmd/Ctrl+click detection (default: true) /
enableCtrlClick?: boolean;

/* Enable debug logging (default: false) /
debugMode?: boolean;
}
`

$3

`typescript
interface EnhancedPushOptions {
/* Force opening in new tab regardless of modifier key /
forceNewTab?: boolean;

/* Open in new tab only if modifier key is pressed (false prevents new tab behavior) /
newTab?: boolean;
}
`

🎛️ Advanced Usage

$3

`typescript
newTabRouter(router, {
debugMode: process.env.NODE_ENV === 'development',
});
`

$3

`typescript
// Force new tab for specific calls
router.push('/external-link', { forceNewTab: true });

// Conditional new tab (only if modifier key is pressed)
router.push('/optional-new-tab', { newTab: true });

// Prevent new tab behavior for specific calls
router.push('/normal-navigation', { newTab: false });
`

🔧 TypeScript Support

The package provides comprehensive TypeScript support with full type definitions:

`typescript
import type {
NewTabRouterConfig,
EnhancedPushOptions,
NewTabRouter,
} from 'vue-router-newtab';

// Your router is now fully typed
const router: NewTabRouter = newTabRouter(
createRouter({
/ ... /
})
);

// newTab push method with full type safety
router.push('/about', { forceNewTab: true });
`

🧪 Testing

$3

`bash
npm run test
`

$3

`bash
npm run test:coverage
`

$3

`bash
npm run test:e2e
`

🌍 Browser Support

- ✅ Chrome 88+
- ✅ Firefox 85+
- ✅ Safari 14+
- ✅ Edge 88+

📦 Bundle Size

- ESM: ~3.2KB gzipped
- CJS: ~3.5KB gzipped

🚨 Important Notes

$3

The new tab router automatically detects server-side environments and skips new tab functionality to prevent SSR errors:

`typescript
// Safe to use in SSR - will be skipped automatically
newTabRouter(router);
`

$3

The new tab router automatically cleans up event listeners when the router is destroyed. For manual cleanup:

`typescript
import { destroyNewTabRouter } from 'vue-router-newtab';

// Clean up when needed
destroyNewTabRouter(router);
`

$3

- New tabs are opened with noopener,noreferrer for security
- External URLs are detected and handled appropriately
- Popup blockers are handled gracefully with fallback to normal navigation

🔄 Migration Guide

$3

The new tab router is designed to be non-intrusive. Your existing code will work without changes:

`typescript
// Before
router.push('/about');

// After (same code, enhanced behavior)
newTabRouter(router);
router.push('/about'); // Now supports Cmd/Ctrl+click!
`

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

$3

`bash


Clone the repository

git clone https://github.com/sjmc11/vue-router-newtab.git

Install dependencies

npm install

Run tests

npm run test

Build the package

npm run build
``

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

- Vue.js team for the amazing framework
- Vue Router team for the excellent routing solution
- All contributors who help make this project better

📞 Support

- 📖 Documentation
- 🐛 Issue Tracker
- 💬 Discussions

---

Made with ❤️ for the Vue.js community