@livx.cc/frame

🏗 Frame

External infrastructure for Vue.js applications

Frame provides a complete, opinionated development environment for Vue.js applications, letting you focus on your views and business logic while Frame handles the infrastructure.

✨ Features

• 🚀 File-based Routing - Automatic route generation from your src/views/ directory
• 🎯 Custom Route Overrides - Override file-based routes with meta, redirects, and guards
• 🎨 Pug Templating - Clean, indentation-based HTML templating out of the box
• 🧠 Meta Management - Dynamic page titles, descriptions, and social media tags
• 🎭 Layout Control - Hide/show header/footer per route with zero FOUC
• ⚡ Vite + Vue 3 - Lightning-fast development with the latest Vue ecosystem
• 📝 TypeScript Support - Full TypeScript integration with proper type definitions
• 🛠 Powerful CLI - Scaffold projects, generate components, and manage configurations
• 🧪 Testing Ready - Vitest integration with utilities and examples
• 💎 Code Quality - ESLint, Prettier, and development best practices
• 🏪 State Management - Optional Pinia integration for complex applications
• 🎨 CSS Flexibility - Full support for Tailwind CSS (with @apply), LESS, SCSS/SASS
• 🔧 Extensible - Customizable configuration and plugin system

🚀 Quick Start

Installation

npm install -g @livx.cc/frame

Create a New Project

# Basic project
frame init my-app

# Full-featured project with all options
frame init my-app --typescript --pinia --testing --eslint --prettier --git

# Create and navigate
frame create my-store --typescript --pinia
cd my-store

Development

# Start development server
frame dev

# Build for production
frame build

# Preview production build
frame preview

# Run tests
frame test

🛠 CLI Commands

Project Initialization

frame init [name] [options]     # Create new Frame project
frame create [name] [options]   # Alias for init

Options:

• --typescript - Use TypeScript
• --eslint - Include ESLint configuration
• --prettier - Include Prettier configuration
• --pinia - Include Pinia store management
• --testing - Include Vitest testing setup
• --git - Initialize git repository

Code Generation

frame scaffold <type> [name] [options]  # Generate code
frame generate <type> [name] [options]  # Alias for scaffold

Types:

• component - Vue component with Pug template
• view - Page view with routing
• composable - Vue composable
• store - Pinia store
• middleware - Route middleware
• layout - Layout component
• plugin - Vue plugin

Options:

• --typescript - Generate TypeScript files
• --test - Include test files

Examples:

frame scaffold component UserProfile --typescript --test
frame generate view ProductDetails --test
frame scaffold composable useApi --typescript
frame generate store userStore --typescript

Project Updates

frame update [options]  # Add features to existing project

Options:

• --pug - Add Pug templating support
• --meta - Add meta management
• --pinia - Add Pinia state management
• --testing - Add Vitest testing
• --eslint - Add ESLint configuration
• --prettier - Add Prettier configuration
• --all - Add all available features

📁 Project Structure

Frame creates a clean, organized project structure:

my-app/
├── src/
│   ├── views/           # Auto-routed page views
│   ├── components/      # Reusable components
│   ├── composables/     # Vue composables
│   ├── store/           # Pinia stores (if enabled)
│   ├── middleware/      # Route middleware
│   ├── layouts/         # Layout components
│   ├── plugins/         # Vue plugins
│   └── tests/           # Test files
├── frame.config.mjs     # Frame configuration
├── tsconfig.json        # TypeScript config (if enabled)
├── vitest.config.ts     # Test config (if enabled)
└── package.json

🎯 Key Features

File-Based Routing

Frame automatically generates routes from your src/views/ directory:

src/views/
├── Home.vue           → /
├── About.vue          → /about
├── [id].vue           → /:id
└── user/
    └── [userId].vue   → /user/:userId

Custom Route Overrides:

You can override file-based routes with custom configurations in frame.config.mjs:

export default {
  routing: {
    customRoutes: [
      {
        path: '/',
        name: 'Home',
        component: './src/views/Home.vue',
        meta: {
          hideHeader: true,
          hideFooter: true,
          title: 'Welcome Home'
        }
      },
      {
        path: '/:pathMatch(.*)*',
        name: 'NotFound',
        component: './src/views/NotFoundView.vue',
        meta: {
          hideHeader: true,
          title: 'Page Not Found'
        }
      }
    ]
  }
}

Custom routes automatically override file-based routes with the same path, giving you full control over route behavior while keeping your views organized.

Meta Management

Dynamic SEO and social media optimization:

<script setup lang="ts">
import { useFrameMeta } from '#frame/meta-helpers';

useFrameMeta({
  title: 'My Amazing Page',
  description: 'This page is built with Frame',
  keywords: ['vue', 'frame', 'awesome'],
  type: 'website'
});
</script>

Pug Templating

Clean, maintainable templates:

<template lang="pug">
div.container
  h1 {{ title }}
  p.description {{ description }}
  button.btn(@click="handleClick") 
    | Click me!
</template>

Layout Control per Route

Control header/footer visibility on a per-page basis using route meta:

1. Configure routes with layout meta:

// frame.config.mjs
export default {
  routing: {
    customRoutes: [
      {
        path: '/login',
        component: './src/views/Login.vue',
        meta: {
          hideHeader: true,
          hideFooter: true
        }
      }
    ]
  }
}

2. Use the router-ready pattern in App.vue:

<template lang="pug">
#app
  nav.header(v-if="showHeader")
    // Your navigation
    
  main
    router-view
    
  footer(v-if="showFooter")
    // Your footer
</template>

<script setup lang="ts">
import { ref, computed, onMounted } from 'vue';
import { useRouter, useRoute } from 'vue-router';

const router = useRouter();
const route = useRoute();
const routerReady = ref(false);

// Prevents flash of header/footer on page load
const showHeader = computed(() => routerReady.value && !route.meta.hideHeader);
const showFooter = computed(() => routerReady.value && !route.meta.hideFooter);

onMounted(async () => {
  await router.isReady();
  routerReady.value = true;
});
</script>

This pattern prevents FOUC (Flash of Unstyled Content) and ensures smooth page transitions.

Component Generation

Generate components with proper structure:

frame scaffold component UserCard --typescript --test

Creates:

• src/components/UserCard.vue - Component with Pug template
• src/tests/components/UserCard.test.ts - Test file

🎨 Styling

Frame supports modern CSS solutions out of the box:

Tailwind CSS with @apply

Use Tailwind's utility-first approach and extract component classes with @apply:

@layer components {
  .btn-primary {
    @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded;
  }
}

LESS & SCSS

Use powerful CSS preprocessors with variables, mixins, and nesting:

<style lang="less" scoped>
@primary: #42b883;

.component {
  background: lighten(@primary, 40%);
  
  &:hover {
    background: lighten(@primary, 30%);
  }
}
</style>

Quick Setup:

# Tailwind CSS
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

# LESS
npm install -D less

# SCSS
npm install -D sass

Frame handles all the configuration automatically. See the CSS Preprocessors Guide for details.

📚 Documentation

Comprehensive guides available in .tmp/ directory:

• CLI Documentation - Complete CLI reference
• Meta Management Guide - SEO and social media optimization
• Pug Usage Guide - Templating with Pug
• Route Customization - Advanced routing
• CSS Preprocessors Guide - Tailwind, LESS, SCSS usage

🧪 Testing

Frame includes Vitest for fast, modern testing:

// src/tests/components/MyComponent.test.ts
import { mount } from '@vue/test-utils';
import { describe, it, expect } from 'vitest';
import MyComponent from '@/components/MyComponent.vue';

describe('MyComponent', () => {
  it('renders correctly', () => {
    const wrapper = mount(MyComponent);
    expect(wrapper.text()).toContain('Expected text');
  });
});

⚙️ Configuration

Customize Frame behavior with frame.config.mjs:

export default {
  // Custom Vite config
  vite: {
    // Your Vite customizations
  },
  
  // Router options
  router: {
    scrollBehavior: 'smooth'
  },
  
  // Meta defaults
  meta: {
    siteName: 'My App',
    themeColor: '#42b883'
  }
};

🤝 Contributing

• Fork the repository
• Create a feature branch: git checkout -b feature/amazing-feature
• Commit your changes: git commit -m 'Add amazing feature'
• Push to the branch: git push origin feature/amazing-feature
• Open a Pull Request

🆘 Support

• Issues: GitHub Issues
• Documentation: Check the .tmp/ directory for detailed guides
• CLI Help: frame --help or frame <command> --help

🎉 Recent Improvements

v1.0.6+ - Routing & Layout Enhancements

Custom Routes Override File-Based Routes

• Custom routes in frame.config.mjs now automatically override file-based routes with the same path
• No more duplicate routes - keep your views organized while having full control
• Clear console logging shows which routes are being overridden

FOUC Prevention for Header/Footer

• New router-ready pattern prevents flash of header/footer on page load
• Smooth, professional page transitions out of the box
• Automatic in all new Frame projects

Enhanced Layout Control

• Use hideHeader and hideFooter route meta flags for per-page layout control
• Perfect for login pages, landing pages, and custom full-screen experiences
• Works seamlessly with the router-ready pattern

See IMPROVEMENTS.md for detailed documentation.

Built with ❤️ for the Vue.js community