readme.md for @start.plus/start.plus

An open-source startpage SaaS for families and companies.
Install
To install the package:
npm install @start.plus/start.plus
# or
pnpm install @start.plus/start.plus
Usage
Running the Server
Start the development server:
pnpm start
This will serve the startpage application on 
http://localhost:3000.
Development Mode
For development with live reload:
pnpm watch
Building
To build the project:
pnpm build
CLI Usage
The package provides a CLI command 
startplus:
startplus
Features
Dashboard
The main startpage view featuring:
Time-based greeting - Dynamic greeting based on time of day (Good morning/afternoon/evening)
Current date display - Full formatted date
Widget grid - Responsive layout for productivity widgets
Search integration - Quick access to search functionality
Widgets
Built-in productivity widgets:
Widget
Description
Clock
Digital clock with date display and timezone support
Search
Multi-engine search bar with Google, DuckDuckGo, Bing, and custom search options
Notes
Quick markdown notes with localStorage persistence
Bookmarks
Quick access bookmark tiles with favicon support
Bookmark Management
Create, edit, and delete bookmarks
Organize bookmarks into folders
Automatic favicon fetching
Search functionality
Import/Export capabilities
Application Shell
Built on 
@design.estate/dees-catalog with:
Full application shell with routing
Main menu navigation
App bar with menus and user profile
Keyboard shortcuts
State persistence
Dark theme
Views
View
Description
Dashboard
Main startpage with widgets
Bookmarks
Bookmark management interface
Settings
Application settings
Architecture
Tech Stack
Category
Technology
Frontend
TypeScript, LitElement, Web Components
UI Library
@design.estate/dees-catalog
State
Custom reactive state with localStorage persistence
Backend
@api.global/typedserver
Build
@git.zone/tsbuild, @git.zone/tsbundle
Dev Server
@git.zone/tswatch
Project Structure
start.plus/
├── ts/                          # Backend
│   ├── index.ts                 # Entry point
│   ├── plugins.ts               # Dependency imports
│   ├── paths.ts                 # Path utilities
│   └── server/                  # Server classes
├── ts_web/                      # Frontend
│   ├── index.ts                 # Entry point
│   ├── plugins.ts               # Dependency imports
│   ├── app/                     # Main app component
│   ├── views/                   # View components
│   ├── components/              # Widget components
│   ├── state/                   # State management
│   └── interfaces/              # TypeScript interfaces
├── html/                        # Static HTML files
├── dist_bundle/                 # Built bundle output
└── test/                        # Tests
State Management
The application uses a simple reactive state system with localStorage persistence:
import { appState } from './state/state.js';
// Get current state
const bookmarks = appState.bookmarks.getState();
// Update state
appState.bookmarks.setState([...bookmarks, newBookmark]);
// Subscribe to changes
appState.bookmarks.select().subscribe((bookmarks) => {
  console.log('Bookmarks updated:', bookmarks);
});
Configuration
Environment Variables
Variable
Default
Description
PORT
3000
Server port
NODE_ENV
development
Environment mode
Server Options
import { StartPlusServer } from '@start.plus/start.plus';
const server = new StartPlusServer({
  port: 3000,
  development: true,
});
await server.start();
Development
Prerequisites
Node.js 18+
pnpm
Setup
# Clone the repository
git clone https://code.foss.global/start.plus/start.plus
# Install dependencies
pnpm install
# Start development
pnpm watch
Testing
pnpm test
Building
pnpm build
PWA Support
Start.plus includes PWA (Progressive Web App) support with:
Web app manifest
Standalone display mode
Theme color configuration
Custom icon
API
StartPlusServer
class StartPlusServer {
  constructor(options?: IStartPlusServerOptions);
  start(): Promise<void>;
  stop(): Promise<void>;
}
interface IStartPlusServerOptions {
  port?: number;
  development?: boolean;
}
State
// Bookmark state
appState.bookmarks.getState(): IBookmark[]
appState.bookmarks.setState(bookmarks: IBookmark[]): void
// Widget state
appState.widgets.getState(): IWidgetConfig[]
appState.widgets.setState(widgets: IWidgetConfig[]): void
// Settings state
appState.settings.getState(): ISettings
appState.settings.setState(settings: ISettings): void
Interfaces
interface IBookmark {
  id: string;
  title: string;
  url: string;
  description?: string;
  favicon?: string;
  folderId?: string;
  tags?: string[];
  createdAt: number;
  updatedAt: number;
  visitCount: number;
  lastVisited?: number;
}
interface IWidgetConfig {
  id: string;
  type: string;
  position: { x: number; y: number };
  size: { width: number; height: number };
  config: Record<string, unknown>;
  enabled: boolean;
}
License
MIT License - see license for details.
Links
Repository
Issues
dees-catalog Documentation