Getting Started

This guide will walk you through creating a simple application using WebAwesome components with Laminar. By the end, you'll have a working web application that displays a WebAwesome button component.

This guide demonstrates one setup approach using Scala CLI and Bun. You can adapt these steps to use your preferred build tools (Mill or sbt) and package managers (npm, yarn, or pnpm).

Prerequisites

This guide uses the following tools, but alternatives are available:

Build Tool

This guide uses Scala CLI to compile Scala code to JavaScript. Install it using Homebrew:

brew install Virtuslab/scala-cli/scala-cli

For other installation methods, visit: https://scala-cli.virtuslab.org/install

Alternative build tools: If you prefer using Mill or sbt, you can adapt the dependency declarations to your build tool's syntax. The core dependencies you'll need are:

org.scala-js::scalajs-dom::2.8.1

com.raquo::laminar::17.2.1

io.github.nguyenyou::webawesome-laminar::3.0.0

Package Manager and Development Server

This guide uses Bun for package management and serving the application. Install it with:

curl -fsSL https://bun.sh/install | bash

For other installation methods, visit: https://bun.sh/install

Alternatives: You can use npm, yarn, or pnpm for package management, and Vite or any other static file server for development. Adapt the commands accordingly.

Create Your Project

Start by creating a new directory for your project:

mkdir myapp && cd myapp

Install WebAwesome

Install the WebAwesome library, which provides the web components we'll use. This example uses Bun, but you can use npm, yarn, or pnpm:

bun add @awesome.me/webawesome

npm install @awesome.me/webawesome

pnpm install @awesome.me/webawesome

yarn add @awesome.me/webawesome

Your project structure should now look like this:

package.json

The package.json file should contain:

package.json

{
  "dependencies": {
    "@awesome.me/webawesome": "3.0.0"
  }
}

Create Application Files

Now let's create the two files needed for your application:

main.scala

This is your main Scala application file. It sets up the Scala.js environment, imports necessary dependencies, and renders a WebAwesome button component:

main.scala

//> using scala 3.7.3
//> using platform scala-js

//> using dep "org.scala-js::scalajs-dom::2.8.1"
//> using dep "com.raquo::laminar::17.2.1"
//> using dep "io.github.nguyenyou::webawesome-laminar::3.0.0"

//> using jsModuleKind es

import org.scalajs.dom

import com.raquo.laminar.api.L.*
import io.github.nguyenyou.webawesome.laminar.*
import scala.scalajs.js
import scala.scalajs.js.annotation.JSImport

@JSImport("@awesome.me/webawesome/dist/styles/webawesome.css", JSImport.Namespace)
@js.native object Stylesheet extends js.Object
val _ = Stylesheet

@main
def run(): Unit = {
  val container = dom.document.getElementById("app")
  render(container, Button()("WebAwesome"))
}

Key parts explained:

The //> using directives are Scala CLI syntax that configure Scala.js and include the necessary dependencies. If using Mill or sbt, declare these dependencies in your build file instead.
The @JSImport annotation imports the WebAwesome CSS stylesheet
The run() function finds the container element and renders a Button component using Laminar

index.html

This HTML file serves as the entry point for your application:

index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/main.js"></script>
  </body>
</html>

The <div id="app"> is where your Laminar application will mount, and the script tag loads the compiled JavaScript.

Your project structure should now look like this:

main.scala

index.html

package.json

Compile Scala.js to JavaScript

Compile your Scala code to JavaScript. This example uses Scala CLI:

scala-cli --power package main.scala -f -o main.js

This command compiles your Scala source code into JavaScript that can run in the browser. The -f flag creates a single file bundle, and -o main.js specifies the output filename.

Using Mill or sbt: Configure your build tool to compile Scala.js and output to main.js (or adjust the script path in index.html to match your output).

After compilation, your project structure will include the generated JavaScript file:

main.scala

main.js

index.html

package.json

Run the Application

Start a local development server. This example uses Bun:

bun index.html

This will start a server and automatically open your browser. Navigate to http://localhost:3000 to see your application running with the WebAwesome button component.

Alternative servers: You can use Vite (vite), Python's HTTP server (python -m http.server), or any other static file server. Adjust the port number if your server uses a different port.

What's Next?

Now that you have a working application, here are some next steps:

Explore the component documentation to see all available WebAwesome components
Check out the Button component to learn about its various options and features
Try adding more components to your application
Customize components using attributes and styling options

On this page