Icecake Go Wasm Framework
⚠ This code is an Alpha version with work in progress.
Icecake is an experimental framework designed to build Web Assembly(WASM) SPA 100% fullstack in GO:
Why
Ealy 2023 Web Assembly generated code is smoosly becoming the new standard for running frontend web applications. But although webassembly source code for front can be easily written in C++, C# or Rust, there's still few solutions to write it in GO.
Existing solutions are too restrictive or too exploratory, furthermore nothing exists when it comes to build a nice app with components as we can do with Angular, React or Vue, and mixing one of these framework to generate webassembly code does not make sens.
So the idea here with icecake is to provide a native GUI framework to develop nice and modern SPA very quickly in GO.
Sources of inspiration:
Tech
- Go 1.23 and it's wasm compiler
- based on the
syscall/js
package
- Snippets use Bulma CSS framework. Bulma is a pure CSS framework without any JS code.
About Web Assembly with go
Some documentation available here https://tinygo.org/docs/guides/webassembly/ and here https://github.com/golang/go/wiki/WebAssembly
Go provides a specific js file called wasm_exec.js
that need to be served by your webpapp. This file mustbe part of the static assets to be served by the server. To get the latest version you can extract it from you go installation: cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" ./website/assets
Project directory layout
The Directory structure follows go ecosystem recommendation.
icecake
├── build # build scripts
│ └── Taskfile.yaml # building task configuration, ic. autobuild the front
│
├── cmd
│ ├── icecake # the icecake CLI command required to run the SPA server
│ │ └── icecake.go
│ └── makedocs # the CLI command used to rebuild the docs website
│ └── main.go
│
├── configs # congigurations files, loaded at server startup
│ ├── dev.env
│ └── prod.env
│
├── internal
│ ├── helper
│ └── testwasm # wasm test environment
│
├── pkg
│ ├── * # see description of packages here under
│
├── website # source codes and assets required by the front
│ ├── docs # sources to rebuild the doc website
│ │ ├── assets
│ │ ├── pages
│ │ ├── saas
│ │ └── [*.*]
│ └── spa # source of the SPA, front anf back
│ └── [*.*]
│
Packages
pkg |
description |
browser |
provides primitives to interact directly with the browser, its navigation hystory and the local or the session storages. |
clock |
provides a timer and a ticker with possibility to add callback functions at every tic and at the end of the timer. |
console |
provides helpers to raise enhanced messages in the browser console. |
dom |
provides primitives to interact with the DOM of a webpage. Traditional node, element, and document's methods can be call in go here. An UISnippet struct and an UIComposer Interface are provided to allow rendering of HTMLSnippet and to handle event listening. |
event |
defines all types of the dom event handlers with their methods |
ick |
core Snippets with html rendering |
└── ickui |
UI of core Snippets with event handler. Compiles with the wasm compiler |
ickcore |
provides the render metadata provider and the global registry of Composers, this needs to be fully reworks. |
icksdk |
usefull functions to call API on the spaserver. |
ickserver |
provides a configurable webserver dedicated to serve an spa with wasm code. |
js |
syscall/js extended with console |
namingpattern |
provides functions to check validity of an HTML name such a a token name or the name of an attribute. |
To Do / WIP
This repo is an Alpha version with many work in progress, with many refactoring to make code more coder friendly.
- TODO: provide a snippet to render the wasm and icecake status
- TODO: handle required css per page and not globally
- TODO: provide ick saas files. Handle it at component level
- TODO: enable unfolding ick-tag with a body, closed by
- TODO: enable to process standard tag or any tag like <h1> or <mytip/> and to add it some modifiers (with the TagBuilder)
- TODO: dom.UI.RefreshContent must update the tag itself if required
Development
We use task
as task runner. See Taskfile Installation doc to install it.
In development mode run the dev
task from the root path with the --watch flag
:
$ task -t ./build/Taskfile.yaml dev --watch
This task:
- moves any changed files in
./web/static/
to ./tmp/website/
- builds/rebuilds any frontend components and the .wasm file
- builds/rebuilds the
./tmp/website/spa.wasm
file according to changes in the web/wasm/main.go
live package documentation
Run godoc -http=:6060
locally to see the go packages documentation.
Editor Configuration
If you are using Visual Studio Code, you can use workspace settings to configure the environment variables for the go tools.
Your settings.json file should look something like this:
{
"go.toolsEnvVars": { "GOARCH": "wasm", "GOOS": "js" }
}
Testing wasm code
Testing front with wasm and DOM components can not be executed with the standard go test
command. To test wasm code into a browser well we need to run a dedicated html page which will execute the wasm test code.
Wasm test code and environement is located into internal/testwasm
.
Run the task task -t ./build/Taskfile.yaml test_wasm
to build all test*.go
files. tests.go
is the wasm entry point that will be executed when you load the dedicated HTML page internal/testswasm/index.html
Testing the back
$ task -t ./build/Taskfile.yaml unit_test
Useful read about go data race detector
Licence
LICENCE