Getting Started with UIX

UIX is an open-source full-stack framework for developing reactive web apps with restorable and shared state. UIX apps run on a deno backend and use state-of-the-art web technologies.

The DATEX JavaScript Library acts as the backbone of UIX, providing useful functionality such as reactivity and cross-device data exchange. In contrast to frameworks like React, UIX provides direct wiring to the DOM for reactivity and does not need a virtual DOM.

Our core principles

• Full compatibility with web standards
• Full compatibility with DATEX and unyt.org Supranet principles
• Both backend and frontend code is written as ES6 TypeScript modules
• No JavaScript bundlers

Main features

• Cross-network reactivity
• Server side rendering with partial hydration
• Hybrid backend/frontend routing
• Cross-realm imports
• Shared memory
• JSX support
• Reusable web components
• SCSS support
• And many more...

UIX aims to simplify all phases of the app development cycle, including design, development, testing and distribution, in order to make the developer experience as convenient as possible. This is why UIX ships with integrated features such as:

• Hot reloading
• Testing library
• Stage management
• Version management
• Automated deployment

CLI Installation

To install uix, you need to install deno first.

Linux / MacOS

$ curl -s https://cdn.unyt.org/uix/install.sh | sh

MacOS (Homebrew)

On MacOS, UIX can also be installed with homebrew:

$ brew tap unyt-org/uix
$ brew install uix

Windows / other systems

Installation via deno install:

$ deno install --import-map https://cdn.unyt.org/uix/importmap.json -Aq -n uix https://cdn.unyt.org/uix/run.ts

Creating a new UIX project

You can create a new UIX project by running

$ uix --init

This creates a new base project (https://github.com/unyt-org/uix-base-project.git) in the current directory and starts the app locally.

Note

We recommend using Visual Studio Code for developing UIX apps.
For syntax highlighting and language support (DATEX, Typescript, deno), the DATEX Workbench extension is required.

Running your UIX app

To run your UIX app, make sure the app.dx configuration file exists. Execute the uix command in the root directory of your application (where the app.dx is located) to initialize and run the project.

$ uix

You can pass the following args to the UIX command line utility:

• -p {PORT}, --port {PORT} - Specify the port
• -b, --watch-backend - Automatically reload the backend deno process when backend files are modified
• -l, --live - Automatically reload connected browsers tabs when files are modified
• -w, --watch - Recompile frontend scripts when files are modified
• -d, --detach - Keep the app running in background
• -r, --reload - Force reload deno caches
• -h, --help - Show the help page

• --hod, --http-over-datex - Enable HTTP-over-DATEX (default: true)
• --stage {STAGE} - Current deployment stage (default: dev)
• --env {NAME=VAL} - Exposed environment variables (for remote deployment)
• --clear - Clear all eternal states on the backend
• --version - Get the version of your UIX installation
• --init - Inititialize a new UIX project
• --import-map {PATH} - Import map path
• --enable-tls - Run the web server with TLS
• --inspect - Enable debugging for the deno process
• --unstable - Enable unstable deno features

To run your UIX project without installing the UIX CLI, you can alternatively run the following command in the project root directory:

$ deno run -A --import-map https://cdn.unyt.org/importmap.json https://cdn.unyt.org/uix/run.ts

Architecture of a UIX Project

With UIX, frontend and backend source code and other resources can be combined in one single project.

.
└── uix-app/
    ├── backend/
    │   ├── .dx                 // Config file for the backend endpoint
    │   └── entrypoint.tsx      // Backend entrypoint
    ├── common/                 // Common modules accessible from backend and frontend
    ├── frontend/
    │   ├── .dx                 // Config file for the frontend endpoint
    │   └── entrypoint.tsx      // Frontend entrypoint
    ├── app.dx                  // App config file
    └── deno.json               // Deno config file

Per default, all files in the frontend directory are only available in browser clients (frontend endpoints), while files in the backend directory are only available for backend endpoints (Deno runtime).

With UIX Cross-Realm Imports, TypeScript/JavaScript/DATEX modules from the backend can be imported and used inside frontend modules.

Files in the common directory can be accessed from both the frontend and backend scope.

The UIX namespace

The UIX namespace can be imported with

import { UIX } from "uix"

This namespace contains some important global properties:

interface UIX {
    Theme: ThemeManager;        // UIX Theme manager to register and activate themes and dark/light mode
    cacheDir: Path;      // URL pointing to the local UIX cache directory (only for backend)
    context: "backend"|"frontend"; // current context in which the process is running
    language: string;    // language ("de" | "en" | ...)
    version: string;     // UIX version ("beta" | "1.0.0" | ...)
}

UIX development

Per default, a UIX app runs in the dev stage.

In this stage, special development features are enabled:

• You can completely reset the current page state with CTRL+R
• Error stacks for backend errors thrown during routing are displayed in the browser
• Source maps for TypeScript files are available in the browser

Running UIX apps locally

Per default, UIX apps run on http://localhost:80. You can specify a custom port with the --port argument if this port is not available on your system or if you want to run multiple UIX simultaneously.

Warning

Keep in mind that the cookies are the same for all localhost apps, regardless of the port. This can lead to unexpected behaviour when opening multiple apps that are running on different localhost ports in the same browser (e.g. endpoint and themes might get overridden).

Helpful articles

• UIX introduction for React developers