@iyulab/modern-app

A client-side SPA framework built on Lit Element by iyulab. It bundles routing, a responsive sidebar layout, theme management, toast notifications, and i18n into a single app singleton.

Installation

npm install @iyulab/modern-app

When to use it

✅ Good fit	❌ Not a good fit
Single Page Applications (SPA)	SSR frameworks (Next.js, Nuxt, SvelteKit)
Admin dashboards and internal tools	Static Site Generation (SSG)
Progressive Web Apps (PWA)	SEO-critical public-facing pages

Quick Start

import { app } from '@iyulab/modern-app';
import { html } from 'lit';

await app.load({
  basepath: '/',
  layout: {
    type: 'sidebar',
    logo: '/assets/logo.svg',
    title: 'My App',
    main: [
      { type: 'link', icon: 'home',  label: 'Home',  href: '/' },
      { type: 'link', icon: 'users', label: 'Users', href: '/users' },
    ],
  },
  routes: [
    { index: true,       render: () => html`<home-page></home-page>` },
    { path: 'users',     render: () => html`<users-page></users-page>` },
    { path: 'users/:id', render: (ctx) => html`<user-detail .userId=${ctx.params.id}></user-detail>` },
  ],
  fallback: {
    render: (ctx) => html`<error-page .error=${ctx.error}></error-page>`,
  },
  theme: { default: 'system' },
});

Skills Usage

AI agent skills for this package are located in skills/modern-app/. Install them with npx skills:

From GitHub:

npx skills add iyulab/node-modern-app

From local node_modules:

npx skills add ./node_modules/@iyulab/modern-app

Core API

Navigation

app.navigate('/users/42');     // push a route
app.router?.go('/users/42');   // via router instance
app.router?.context;           // current RouteContext

Theme

app.theme.get();         // 'system' | 'light' | 'dark' | undefined
app.theme.set('dark');
app.theme.isInitialized; // boolean

Notifications

await app.success('Saved!', { title: 'Done', duration: 4000, position: 'top-right' });
await app.error('Something went wrong');
await app.info('Info message');
await app.warning('Double-check this');
await app.notice('Neutral notice');

Localization (i18next)

// Pass i18next plugins and InitOptions
await app.load({
  // ...
  i18n: {
    plugins: [i18nextHttpBackend],
    lng: 'en',
    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' },
  },
});

// Access i18next
app.i18n.t('common::greeting');
app.i18n.changeLanguage('ko');

// Reactive translations in Lit templates
import { translate } from 'lit-i18n';
html`<p>${translate('common::greeting')}</p>`;

Documentation

Guide	Description
getting-started.md	Bootstrap, architecture, entry point setup
routing.md	Route config, URL params, async routes, progress
layout.md	Sidebar layout, all menu item types, responsive behaviour
theme.md	Theme init, runtime switching, CSS tokens
notifications.md	Toast methods and options
i18n.md	i18next setup, plugins, lit-i18n usage
configuration.md	Full TypeScript interface reference

License

MIT