Siegel   

Siegel is a lightweight, opinionated web development platform designed for building scalable client side rendered (CSR) single page applications (SPAs). It aims to simplify the development process.

Features:

• Pre-configured and easily extendable Webpack bundler:

  • SWC loader to transform TypeScript and JSX syntaxes
  • Code linting with ESLint
  • Hot Modules Replace for scripts and styles
  • SASS with typed CSS modules
  • Build and serve site assets compressed with Brotli or GZIP
  • SVG icons to font converter
    
    

• ExpressJS static server:

  • Supports HTTP/1.1 and HTTP/2, with a script for generating development certificates for local Chrome use
    
    

• Utils and modules to use on client side:

  • A comprehensive set of React components
  • Easy configurable Router
  • React global state manager built on top of react hooks
  • Optional fetch module for tracking requests statuses
  • Network services for making requests and a minimal client WebSocket implementation
    
    

• Demo project with pre-themed components, a predefined folder structure, and a scalable architecture built on Siegel
  This facilitates a rapid project start after initialization

• Global TS utility types are available, enchancing development of your React project

Read more about each part following the links below:

• Client core
  • UI components - Common and lightweight React UI components
  • Routing - Built-in routing system, simplifying navigation within your SPA and enabling efficient page management
  • Global store - Allows you to easily create and manage global stores built on top of React hooks
  • Custom hooks - A selction of React to aid in site creation
  • Networking - Tools for a network data transmission
  • Utils - Web related small utilities
• Core
  • Build - Webpack abstraction to easily configure a build process
  • Server - Minimalistic HTTP1.1(S) / HTTP2(S) servers built with ExpressJS
  • Utils - NodeJS related utils
• Cross env utils - Basic utils to help you process data
• TS utils - Useful TypeScript generics
• Demo project - Examle project demonstrating Siegel abilities
• Demo mini project - Examle minimal project demonstrating Siegel abilities

Getting started

Install Siegel as a project dependency with npm:

npm i siegel

Create a new file named app.ts in your project root directory and add the following code:

import { createRoot } from 'react-dom/client'

const root = document.getElementById('root')
createRoot(root)
    .render('Hello Siegel!')

Run the app with the next command:

npx siegel run

Your app will now be running on localhost:3000 in watch mode, enabling live development.

Additionaly, uou can define a custom NodeJS development server using the --server flag.
Create a server.ts file with the following content:

// server.ts

import type { ServerExtenderFn, ExpressExtenderParams } from 'siegel'

const appServer: ServerExtenderFn = params => {
    const { express, staticServer } = params as ExpressExtenderParams

    staticServer
        .use(express.json())
}

export default appServer

To start the app with the custom server, execute the following command:

npx siegel run --server server.ts

Siegel provides a command to initialize a minimal project, including the server.ts and app.ts files created earlier:

npx siegel init -s

To view a list of all available Siegel CLI commands and flags, run: npx siegel

Basic usage

Siegel is composed of client sude and server side modules that can be used independently or in combination.
To launch Siegel, import the module and call it with a
config object

import siegel from 'siegel'

siegel(config)

Alternatively, you can provide the entry point to your React application and Siegel will handle the remaining configs:

import siegel from 'siegel'

siegel('/path/to/js_entry.ts')

Config

Build config
Server config

{   
    runMode: {
        /* Run static server. Default is true */
        isServer: Boolean,

        /* Build a project. Default is true */
        isBuild: Boolean,

        /* Run Siegel in production mode. Default is false */
        isProd: Boolean
    },

    /*
        Affects both server(as public dir to be served),
        and client_build(as webpack output folder).
        Default is: path.join(process.cwd(), 'dist')
    */
    publicDir: String,

    /* Static server config. */
    server: Object,

    /* Build config. */
    build: Object
}

Demo project setup

The demo project provides a quick start for your development journey, offering all necessary components immediately after initialization.

Install Siegel as a project dependency with npm:

npx siegel init

This comman initializes a demo project in the current directory, including a package.json if not one does not already exist.
The project now has pre-configured Siegel project structure.
Use the various npm commands within the generated package.json to build, validate and server the project in development or production modes.
Start the newly created project with:

npm start

For quick experimentation, you may not need to initialize a full demo project.
Therefore, you can initialize a minimal project by passing the -m flag to the siegel init command.
This creates only a client-side React entry file and a tsconfig.json file.
Optionally you can also pass the -s flag to create a server extender file.

npm init -m -s

To run the minimal project, use npm start_client if a server extender was not created.
Otherwise use npm start

Read more about demo project here

VSCode tweaks

In order to enable all the features that Siegel provides, you should first change some settings in your VSCode:

{
    "typescript.tsdk": "./node_modules/typescript/lib",
    "eslint.useFlatConfig": true
}

typescript.tsdk - to tell TS extension to load ts plugins from your tsconfig.json

eslint.useFlatConfig - to tell ESLint to use .js config file extension by default

Siegel development

In case you've cloned this repo:

To build Siegel run:

npm run __transpile

To start a local development with provided Demo Application run:

npm start