npm package: @livx.cc/frame
Description: External infrastructure for Vue.js applications
Author: Livshitz
Latest version: 1.1.7

# 🏗 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

```bash
npm install -g @livx.cc/frame
```

### Create a New Project

```bash
# 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

```bash
# Start development server
frame dev

# Build for production
frame build

# Preview production build
frame preview

# Run tests
frame test
```

## 🛠 CLI Commands

### Project Initialization

```bash
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

```bash
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:**
```bash
frame scaffold component UserProfile --typescript --test
frame generate view ProductDetails --test
frame scaffold composable useApi --typescript
frame generate store userStore --typescript
```

### Project Updates

```bash
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`:

```javascript
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:

```vue
<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:

```vue
<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:**

```javascript
// 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:**

```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:

```bash
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`:

```css
@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:

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

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

**Quick Setup:**

```bash
# 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](./.tmp/css-preprocessors-guide.md) for details.

## 📚 Documentation

Comprehensive guides available in `.tmp/` directory:

- **[CLI Documentation](./cli-documentation.md)** - Complete CLI reference
- **[Meta Management Guide](./meta-usage-guide.md)** - SEO and social media optimization
- **[Pug Usage Guide](./pug-usage-guide.md)** - Templating with Pug
- **[Route Customization](./route-customization-guide.md)** - Advanced routing
- **[CSS Preprocessors Guide](./.tmp/css-preprocessors-guide.md)** - Tailwind, LESS, SCSS usage

## 🧪 Testing

Frame includes Vitest for fast, modern testing:

```typescript
// 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`:

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

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'Add amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Open a Pull Request

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/org/frame/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](./IMPROVEMENTS.md) for detailed documentation.

---

Built with ❤️ for the Vue.js community