Go WebView CEF

A cross-platform Go binding for Chromium Embedded Framework (CEF) providing a webview-compatible API for building desktop applications with web technologies.

Features

✅ Cross-Platform: Linux, macOS, Windows support
✅ WebView-Compatible API: Drop-in replacement for webview/webview
✅ CEF Integration: Full Chromium browser engine
✅ JavaScript Bindings: Call Go functions from JavaScript
✅ WSL/WSLg Support: Works on Windows Subsystem for Linux

Supported Platforms

Platform	Architecture	Status	Notes
Linux	x64 (amd64)	✅ Working	Tested on Ubuntu/Debian
Linux	ARM64	⚠️ Ready	Build tags implemented
macOS	x64 (amd64)	⚠️ Ready	Build tags implemented, needs testing
macOS	ARM64 (M1/M2)	⚠️ Ready	Build tags implemented, needs testing
Windows	x64 (amd64)	⚠️ Ready	Build tags implemented, needs testing
Windows	ARM64	⚠️ Ready	Build tags implemented, needs testing

Quick Start

Prerequisites

Go 1.26 or later
C compiler (gcc/clang on Linux/macOS, MinGW on Windows)
For WSL: WSL2 with WSLg support (xeyes should work)
For Linux: X11 or Wayland display server

Installation

# Clone the repository
git clone https://github.com/xelus/go-webview-cef.git
cd go-webview-cef

# Download CEF binaries (automatically detects platform)
go run scripts/setup_cef.go

# Build the demo
./run.sh build

# Run the demo
./run.sh run

Usage

Basic Example

package main

import (
    "github.com/xelus/go-webview-cef/adapter/webview"
)

func main() {
    w := webview.New(false)
    defer w.Destroy()

    w.Bind("add", func(a, b int) int {
        return a + b
    })

    w.SetTitle("My App")
    w.SetSize(1024, 768, webview.HintNone)

    w.Navigate(`data:text/html,<!DOCTYPE html>
<html>
<body>
    <h1>Go + CEF</h1>
    <button onclick="test()">Call Go</button>
    <script>
        async function test() {
            const result = await add(5, 3);
            alert("5 + 3 = " + result);
        }
    </script>
</body>
</html>`)

    w.Run()
}

API Reference

WebView Interface

type WebView interface {
    Run()
    Terminate()
    Destroy()
    Window() unsafe.Pointer
    SetTitle(title string)
    SetSize(width, height int, hint int)
    Navigate(url string)
    Init(js string)
    Eval(js string)
    Bind(name string, fn interface{}) error
    Unbind(name string) error
}

Window Hints

const (
    HintNone  = 0
    HintFixed = 1
    HintMin   = 2
    HintMax   = 3
)

Project Structure

.
├── adapter/webview/          # WebView-compatible API
├── cef/                      # Public API wrappers
├── internal/cefbindings/     # Generated binding types (committed)
├── internal/cefruntime/      # Go-owned runtime state/lifecycle/IPC
├── internal/cefshim/         # Minimal cgo/ABI shim + CEF runtime C file
├── runtime/cef_runtime.h     # Stable C ABI boundary header
├── scripts/                  # Setup + diagnostics + generators
├── example/                  # Example apps
├── third_party/cef/          # Downloaded CEF binaries (gitignored)
└── run.sh                    # Build & run script

Build Commands

Linux/WSL

# Native build
go build -o build/demo ./cmd/demo

# Using the run script
./run.sh build
./run.sh run

# Cross-compile for other platforms
GOOS=darwin GOARCH=amd64 go build -o build/demo ./cmd/demo
GOOS=windows GOARCH=amd64 go build -o build/demo.exe ./cmd/demo

macOS

# Download CEF for macOS
go run scripts/setup_cef.go

# Build
go build -o build/demo ./cmd/demo

# Run
./build/demo

Windows

# Download CEF for Windows
go run scripts/setup_cef.go

# Build (requires MinGW)
go build -o build/demo.exe ./cmd/demo

# Run
.\build\demo.exe

CEF Configuration

The implementation uses CEF's C API with a Go-first runtime architecture:

internal/cefruntime: Go lifecycle, browser registry, JS bridge dispatch.
internal/cefshim: minimal cgo boundary and callback trampolines.
internal/cefshim/cef_runtime_impl.c: single active C runtime implementation.

CEF Download URLs

All platforms use .tar.bz2 archives:

Linux: cef_binary_*_linux64.tar.bz2
macOS: cef_binary_*_macosx64.tar.bz2
Windows: cef_binary_*_windows64.tar.bz2

WSL/WSLg Compatibility

The implementation includes WSL-specific flags for GPU/graphics compatibility:

--no-sandbox
--disable-gpu
--disable-gpu-compositing
--use-gl=swiftshader
--single-process

Troubleshooting

Display Issues (WSL/Linux)

If you see GPU errors or display issues:

# Check if DISPLAY is set
echo $DISPLAY

# For WSLg, should be something like: :0
# If not set, try:
export DISPLAY=:0

# Run with the script which sets this automatically
./run.sh run

Missing Libraries

If you get library loading errors:

# Linux/WSL
export LD_LIBRARY_PATH=$PWD/build:$LD_LIBRARY_PATH

# macOS
export DYLD_LIBRARY_PATH=$PWD/build:$DYLD_LIBRARY_PATH

# Windows (PowerShell)
$env:PATH = "$PWD/build;$env:PATH"

CEF Not Found

If CEF binaries are not found:

# Re-download CEF
rm -rf third_party/cef
go run scripts/setup_cef.go

Architecture

┌─────────────────┐
│   App Code      │  Your Go application
├─────────────────┤
│ WebView Adapter │  webview.New(), w.Run()
├─────────────────┤
│  cef package     │  Public compatibility wrappers
├─────────────────┤
│  Go Runtime Core │  internal/cefruntime
├─────────────────┤
│  ABI Shim (cgo)  │  internal/cefshim
├─────────────────┤
│   CEF C API      │  cef_initialize(), cef_browser_create()
├─────────────────┤
│   libcef         │  Chromium Embedded Framework
└─────────────────┘

Development Status

✅ CEF downloader with auto-platform detection
✅ C wrapper with proper initialization flow
✅ Go bindings with platform-specific build tags
✅ WebView-compatible adapter layer
✅ OnContextInitialized callback for browser creation
✅ WSL/WSLg compatibility
✅ Multi-process model support
✅ Cross-platform build system
⚠️ macOS testing needed
⚠️ Windows testing needed

Contributing

Contributions are welcome! Areas that need help:

macOS Testing: Verify build and runtime on macOS
Windows Testing: Verify build and runtime on Windows
Documentation: Improve setup instructions
Examples: Add more usage examples

Please submit issues and pull requests on GitHub.

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2026 Xelus

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Acknowledgments

Chromium Embedded Framework - The CEF project
Spotify CEF Builds - Prebuilt CEF binaries

Notes

CEF binaries are ~150-300MB per platform
The implementation uses CEF's C API (not C++) for better compatibility
Single-process mode is used for simplified deployment (not recommended for production)
For production use, consider implementing proper multi-process handling
Window management is platform-specific and may need adjustments for each OS

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github/workflows		.github/workflows
adapter/webview		adapter/webview
cef		cef
cmd		cmd
example		example
integration/wails		integration/wails
internal		internal
runtime		runtime
scripts		scripts
.gitignore		.gitignore
CROSS_PLATFORM.md		CROSS_PLATFORM.md
IMPLEMENTATION_COMPLETE.md		IMPLEMENTATION_COMPLETE.md
IMPLEMENTATION_STATUS.md		IMPLEMENTATION_STATUS.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
LICENSE		LICENSE
MINIMUM_C_REFACTOR.md		MINIMUM_C_REFACTOR.md
Makefile		Makefile
README.md		README.md
STATUS_WORKING.md		STATUS_WORKING.md
WEBVIEW2_CEF_OPTIONS.md		WEBVIEW2_CEF_OPTIONS.md
cef145_test		cef145_test
go.mod		go.mod
run.sh		run.sh

Folders and files

Latest commit

History

Repository files navigation

Go WebView CEF

Features

Supported Platforms

Quick Start

Prerequisites

Installation

Usage

Basic Example

API Reference

WebView Interface

Window Hints

Project Structure

Build Commands

Linux/WSL

macOS

Windows

CEF Configuration

CEF Download URLs

WSL/WSLg Compatibility

Troubleshooting

Display Issues (WSL/Linux)

Missing Libraries

CEF Not Found

Architecture

Development Status

Contributing

License

Acknowledgments

Notes

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages