npm package: @htlkg/astro
Description: Astro integration, layouts, page patterns, middleware, and utilities for Hotelinking applications.
Latest version: 0.0.26

# @htlkg/astro

Astro integration, layouts, page patterns, middleware, and utilities for Hotelinking applications.

## Modules

### [htlkg Integration](src/htlkg/htlkg.md)
Zero-config Astro integration with automatic middleware, route guards, and virtual modules.

### [Layouts](src/layouts/layouts.md)
Page layouts: AdminLayout, BrandLayout, AuthLayout, PublicLayout.

### [Middleware](src/middleware/middleware.md)
Authentication middleware and route guards: `requireAuth`, `requireAdminAccess`, `requireBrandAccess`.

### [Components](src/components/components.md)
Astro components: Sidebar, Topbar, PageHeader, Island.

### [Patterns](src/patterns/patterns.md)
Reusable page patterns for admin and brand pages.

### [Utils](src/utils/utils.md)
SSR, hydration, and static rendering helpers.

### [Auth](src/auth/auth.md)
Authentication pages and components: LoginPage, LoginForm.

## Overview

`@htlkg/astro` consolidates all Astro-specific functionality into a single package.

## Installation

```bash
pnpm add @htlkg/astro
```

## Quick Start

### 1. Configure Astro Integration

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import { htlkg } from '@htlkg/astro';

export default defineConfig({
  integrations: [
    htlkg({
      auth: {
        enabled: true,
        loginPage: '/login',
        publicRoutes: ['/login', '/public'],
      },
      brandRoutes: {
        enabled: true,
        pattern: '/[brandId]',
      },
    }),
  ],
});
```

### 2. Use Layouts

```astro
---
// src/pages/admin/brands.astro
import { AdminLayout } from '@htlkg/astro/layouts';
import { BrandsPage } from '@/components';

const user = Astro.locals.user;
---

<AdminLayout user={user} title="Brands">
  <BrandsPage />
</AdminLayout>
```

### 3. Apply Middleware

```astro
---
// src/pages/admin/users.astro
import { requireAdminAccess } from '@htlkg/astro/middleware';

export const prerender = false;

// Require admin access
await requireAdminAccess(Astro);
---
```

## Package Structure

```
@htlkg/astro/
├── auth/              # Authentication pages
│   └── LoginPage.astro
├── components/        # Astro components
│   ├── PageHeader.astro
│   ├── Sidebar.astro
│   └── Topbar.astro
├── htlkg/            # Astro integration
│   ├── index.ts      # Main integration
│   └── config.ts     # Configuration types
├── runtime-config.ts # Runtime configuration storage
├── layouts/          # Page layouts
│   ├── AdminLayout.astro
│   ├── BrandLayout.astro
│   ├── AuthLayout.astro
│   └── PublicLayout.astro
├── middleware/       # Middleware & route guards
│   ├── auth.ts
│   ├── route-guards.ts
│   └── index.ts
├── patterns/         # Page patterns
│   ├── admin/
│   │   ├── ListPage.astro
│   │   ├── DetailPage.astro
│   │   └── FormPage.astro
│   └── brand/
│       ├── ConfigPage.astro
│       └── PortalPage.astro
└── utils/            # Utilities
    ├── hydration.ts  # Client hydration helpers
    ├── ssr.ts        # Server-side rendering helpers
    └── static.ts     # Static generation helpers
```

## Exports

### Main Package (`@htlkg/astro`)

```typescript
import { htlkg } from '@htlkg/astro';
import type { HtlkgIntegrationOptions, AuthUser } from '@htlkg/astro';
```

### Layouts

```typescript
import { AdminLayout } from '@htlkg/astro/layouts';
import { BrandLayout } from '@htlkg/astro/layouts';
import { AuthLayout } from '@htlkg/astro/layouts';
import { PublicLayout } from '@htlkg/astro/layouts';
```

### Middleware

```typescript
import {
  requireAdminAccess,
  requireBrandAccess,
  requireAuth,
} from '@htlkg/astro/middleware';
```

### Page Patterns

```typescript
import { ListPage } from '@htlkg/astro/patterns/admin';
import { DetailPage } from '@htlkg/astro/patterns/admin';
import { FormPage } from '@htlkg/astro/patterns/admin';
import { ConfigPage } from '@htlkg/astro/patterns/brand';
```

### Components

```typescript
import { Sidebar } from '@htlkg/astro/components';
import { Topbar } from '@htlkg/astro/components';
import { PageHeader } from '@htlkg/astro/components';
```

### Utilities

```typescript
import { getHydrationStrategy } from '@htlkg/astro/utils/hydration';
import { getSSRConfig } from '@htlkg/astro/utils/ssr';
import { getStaticPaths } from '@htlkg/astro/utils/static';
```

## Features

### Astro Integration

The `htlkg()` integration provides:

- Automatic middleware setup
- Route guard configuration
- Login page injection
- Brand route handling
- Virtual module configuration

### Layouts

Pre-built layouts for common page types:

- **AdminLayout** - Admin portal pages with sidebar navigation
- **BrandLayout** - Brand-specific pages with brand context
- **AuthLayout** - Authentication pages (login, signup)
- **PublicLayout** - Public-facing pages

### Middleware

Authentication and authorization middleware:

- **requireAuth** - Require authenticated user
- **requireAdminAccess** - Require admin role
- **requireBrandAccess** - Require brand access

### Page Patterns

Reusable page templates:

- **ListPage** - List/table view with filters
- **DetailPage** - Detail view with tabs
- **FormPage** - Form view with validation
- **ConfigPage** - Configuration page

## Configuration

### Integration Options

```typescript
interface HtlkgIntegrationOptions {
  auth?: {
    enabled: boolean;
    loginPage?: string;
    publicRoutes?: RoutePattern[];
    protectedRoutes?: RoutePattern[];
  };
  brandRoutes?: {
    enabled: boolean;
    pattern?: string;
  };
}
```

### Route Guards

```typescript
interface RouteGuardConfig {
  publicRoutes: RoutePattern[];
  protectedRoutes: RoutePattern[];
  loginPage: string;
  brandRoutePattern?: RegExp;
}
```

## Dependencies

- `astro` - Astro framework
- `@astrojs/vue` - Vue integration
- `@astrojs/tailwind` - Tailwind CSS integration
- `@htlkg/core` - Core utilities and types
- `@htlkg/components` - Vue components
- `vue` - Vue framework
- `tailwindcss` - Tailwind CSS

## Development

```bash
# Build package
pnpm build

# Watch mode
pnpm dev

# Run tests
pnpm test
```

## Migration

If migrating from `@htlkg/pages` and `@htlkg/integrations`, see [MIGRATION_ASTRO_PACKAGE.md](../../MIGRATION_ASTRO_PACKAGE.md).

## License

Private - Hotelinking internal use only