@htlkg/astro

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

Modules

htlkg Integration

Zero-config Astro integration with automatic middleware, route guards, and virtual modules.

Layouts

Page layouts: AdminLayout, BrandLayout, AuthLayout, PublicLayout.

Middleware

Authentication middleware and route guards: requireAuth, requireAdminAccess, requireBrandAccess.

Components

Astro components: Sidebar, Topbar, PageHeader, Island.

Patterns

Reusable page patterns for admin and brand pages.

Utils

SSR, hydration, and static rendering helpers.

Auth

Authentication pages and components: LoginPage, LoginForm.

Overview

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

Installation

pnpm add @htlkg/astro

Quick Start

1. Configure Astro Integration

// 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

---
// 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

---
// 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
│   └── virtual-modules.ts
├── 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)

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

Layouts

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

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

Page Patterns

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

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

Utilities

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

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

Route Guards

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

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

License

Private - Hotelinking internal use only