125a67826e | ||
---|---|---|
.github | ||
.vscode | ||
Sources/carton | ||
TestApp | ||
Tests | ||
entrypoint | ||
.gitignore | ||
.pre-commit-config.yaml | ||
.swift-version | ||
.swiftformat | ||
.swiftlint.yml | ||
Brewfile | ||
CHANGELOG.md | ||
CODE_OF_CONDUCT.md | ||
Dangerfile.swift | ||
LICENSE | ||
Package.resolved | ||
Package.swift | ||
README.md | ||
package-lock.json | ||
package.json | ||
webpack.config.js |
README.md
carton 📦
Watcher, bundler, and test runner for your SwiftWasm apps
The main goal of carton
is to provide a smooth zero-config experience when developing for WebAssembly.
It is still in development, but it aims to support these features (🐥 means "ready to use"):
- 🥚 Creating basic package boilerplate for apps built with SwiftWasm with
carton init
. - 🐥 Watching the app for source code changes and reloading it in your browser with
carton dev
. - 🐣 Running your XCTest suite in the full JavaScript/DOM environment with
carton test
. - 🥚 Optimizing and packaging the app for distribution with
carton bundle
.
It is currently work in progress, so watch the repository for imminent updates!
Motivation
The main motivation for carton
came after I had enough struggles with webpack.js,
trying to make its config file work, looking for appropriate plugins. I'm convinced that the required use of
webpack
in SwiftWasm projects could limit the wider adoption of SwiftWasm itself. Hopefully, with carton
you can avoid using webpack
altogether.
Requirements
- macOS 10.15 and Xcode 11.4 or later for macOS users.
- Swift 5.2 or later for Linux users.
On either platform you should install cross-compilation SwiftWasm toolchain via
swiftenv
as described in the SwiftWasm
Book, in addition to the
host Swift 5.2 toolchain mentioned above.
In the future, manual installation of SwiftWasm won't be required, please see issue #3 for more details.
Installation
On macOS carton
can be installed with Homebrew. Make sure you have Homebrew
installed and then run:
brew tap swiftwasm/tap
brew install carton
You'll have to build carton
from sources on Linux. Clone the repository and run
swift build -c release
, the carton
binary will be located in the .build/release/carton
directory after that.
How does it work?
carton
bundles a WASI polyfill, which is currently required to run any SwiftWasm code,
and the JavaScriptKit runtime for convenience.
carton
also embeds an HTTP server for previewing your SwiftWasm app directly in a browser.
The development version of the polyfill establishes a helper WebSocket connection to the server, so that
it can reload development browser tabs when rebuilt binary is available. This brings the development
experience closer to Xcode live previews, which you may have previously used when developing SwiftUI apps.
carton
does not require any config files for these basic development scenarios, while some configuration
may be supported in the future, for example for complex asset pipelines if needed. The only requirement
is that your Package.swift
contains at least a single executable product, which then will be compiled
for WebAssembly and served when you start carton dev
in the directory where Package.swift
is located.
carton
is built with Vapor, SwiftNIO,
swift-tools-support-core, and
OpenCombine, and supports both macOS and Linux. (Many
thanks to everyone supporting and maintaining those projects!)
Roadmap
Since a subset of Foundation and XCTest already work and are supplied in the latest snapshots of
SwiftWasm SDK, the next top priority for carton
is to allow running your XCTest suites directly in
browsers and receiving test results back to the HTTP server, so that test results can be reported in CLI.
This was blocked by XCTest
not allowing customized test report formats,
which is now partially resolved with a new argument available on
XCTMain
and a custom JSON test
reporter. After a few other
issues are resolved with the SwiftWasm toolchain, I'll get
carton test
fully working with XCTest.
There are a few more commands on the roadmap to be implemented, such as carton init
for initializing
basic SwiftWasm projects (potentially with configurable templates), carton bundle
to produce an
optimized production deployment bundle, SwiftPM resources support for bundled assets, carton sdk
command for SDK installation and management and much more.
As cross-compiling to WebAssembly and running apps and tests remotely is not too dissimilar to Android
development, or even development on macOS for Linux through Docker, carton
could potentially become
a generic tool for cross-platform Swift developers. I'm not developing any Android apps currently, but
if there are interested Swift for Android developers, I'd be very happy to review and merge their
contributions enabling that.
Contributing
Sponsorship
If this tool saved you any amount of time or money, please consider sponsoring the work of its maintainer. While some of the sponsorship tiers give you priority support or even consulting time, any amount is appreciated and helps in maintaining the project.
Coding Style
This project uses SwiftFormat and SwiftLint to enforce formatting and coding style. We encourage you to run SwiftFormat within a local clone of the repository in whatever way works best for you either manually or automatically via an Xcode extension, build phase or git pre-commit hook etc.
To guarantee that these tools run before you commit your changes on macOS, you're encouraged to run this once to set up the pre-commit hook:
brew bundle # installs SwiftLint, SwiftFormat and pre-commit
pre-commit install # installs pre-commit hook to run checks before you commit
Refer to the pre-commit documentation page for more details and installation instructions for other platforms.
SwiftFormat and SwiftLint also run on CI for every PR and thus a CI build can fail with incosistent formatting or style. We require CI builds to pass for all PRs before merging.
Code of Conduct
This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to conduct@carton.dev.