Northstar Web Application Stack

The web/libs/ directory serves as the entrypoint for custom JavaScript and TypeScript libraries. Currently, the project utilizes:

• Web Components: Custom elements located in ./libs/web-components/.
• Lit Components: Lit-based web components located in ./libs/lit/src/components/.

The project uses Go build tags to switch between serving static assets from the local filesystem (development) or from within the compiled binary (production).

Development Mode

Use the -tags=dev build tag. This utilizes static_dev.go to provide an HTTP handler that serves assets directly from the filesystem without embedding them. This allows for faster iteration without re-compiling the binary for every asset change.

Production Mode

Use the -tags=prod build tag (or omit build tags entirely). This utilizes static_prod.go to embed the static assets directly into the binary using hashfs. This ensures the binary is self-contained and ready for deployment.

go build -tags=dev .
# or
go build -tags=prod .

To run the server without live reload, use the run task.

go tool task run

The project uses Air and esbuild for live reloading. Use the live task from the Taskfile to start the development server with live reload enabled. Once started, the application is accessible at http://localhost:8080.

go tool task live

Use the build task to assemble and build the project binary.

go tool task build

To start a debugging session using delve, use the debug task provided by the Taskfile.

go tool task debug

When updating any directory paths within the web/ directory, you must manually synchronize the changes in two locations to prevent build failures:

1. esbuild entrypoints: Update the entrypoint paths in cmd/web/build/main.go.
2. Taskfile: Update the pathing definitions in the root Taskfile.yml.

To set up the development environment for the Web Components library, you must first ensure Go dependencies are synchronized and then run the build script located in the cmd/web/build/main.go path. This process prepares the environment for building custom elements driven by Datastar.

go mod tidy
go run cmd/web/build/main.go

To set up the project locally, clone the repository and install the Go dependencies using go mod tidy.

git clone https://github.com/zangster300/northstar.git
go mod tidy

You can containerize the application using the provided Dockerfile. Build the image and run it by mapping port 8080 on your host to port 9001 in the container.

# build an image
docker build -t northstar:latest .

# run the image in a container
docker run --name northstar -p 8080:9001 northstar:latest

To set up the Lit library example, which is used for creating web components powered by Lit and driven by Datastar, follow these steps:

1. Install the necessary dependencies using pnpm.
2. Run the build command using the Go build tool to prepare the environment.

pnpm install
go run cmd/web/build/main.go

The Northstar web server is the primary entrypoint for the application. It initializes a JSON-based logger, sets up a cookie-based session store, establishes a NATS connection, and configures the HTTP router. The server is designed to handle graceful shutdowns via OS interrupt signals (e.g., Ctrl+C), allowing up to 5 seconds for active connections to close before forcing a shutdown.

# To run the server, use the standard Go run command from the project root
go run cmd/web/main.go