{"id":13498005,"url":"https://github.com/swiftwasm/carton","last_synced_at":"2025-04-05T04:14:40.394Z","repository":{"id":37012596,"uuid":"261237288","full_name":"swiftwasm/carton","owner":"swiftwasm","description":"📦 Watcher, bundler, and test runner for your SwiftWasm apps","archived":false,"fork":false,"pushed_at":"2024-04-04T18:24:38.000Z","size":3140,"stargazers_count":372,"open_issues_count":34,"forks_count":44,"subscribers_count":16,"default_branch":"main","last_synced_at":"2024-04-14T04:01:38.813Z","etag":null,"topics":["bundler","developer-tools","swift","swiftwasm","test-runner","wasm","watcher","webassembly","webpack"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swiftwasm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":["swiftwasm","carson-katri","kateinoigakukun","MaxDesiatov"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2020-05-04T16:26:08.000Z","updated_at":"2024-05-22T06:45:59.609Z","dependencies_parsed_at":"2023-01-17T13:16:02.765Z","dependency_job_id":"ff301ab0-e7ae-40d9-9a6d-babbc4ebdc55","html_url":"https://github.com/swiftwasm/carton","commit_stats":{"total_commits":562,"total_committers":24,"mean_commits":"23.416666666666668","dds":0.402135231316726,"last_synced_commit":"f286203b0d0a32575e5fe05ab358169b5285ffd6"},"previous_names":[],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftwasm%2Fcarton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftwasm%2Fcarton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftwasm%2Fcarton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swiftwasm%2Fcarton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swiftwasm","download_url":"https://codeload.github.com/swiftwasm/carton/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247284953,"owners_count":20913704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bundler","developer-tools","swift","swiftwasm","test-runner","wasm","watcher","webassembly","webpack"],"created_at":"2024-07-31T20:00:48.219Z","updated_at":"2025-04-05T04:14:40.369Z","avatar_url":"https://github.com/swiftwasm.png","language":"Swift","funding_links":["https://github.com/sponsors/swiftwasm","https://github.com/sponsors/carson-katri","https://github.com/sponsors/kateinoigakukun","https://github.com/sponsors/MaxDesiatov","https://github.com/sponsors/swiftwasm/"],"categories":["Developer tools","Swift"],"sub_categories":[],"readme":"# carton 📦\n\n## Watcher, bundler, and test runner for your [SwiftWasm](https://swiftwasm.org/) apps\n\nThe main goal of `carton` is to provide a smooth zero-config experience when developing for WebAssembly.\nIt currently supports these features with separate commands:\n\n- Watching the app for source code changes and reloading it in your browser with `swift run carton dev`.\n- Running your XCTest suite in the full JavaScript/DOM environment with `swift run carton test`.\n- Optimizing and packaging the app for distribution with `swift run carton bundle`.\n\n## Motivation\n\nThe main motivation for `carton` came after having enough struggles with\n[webpack.js](https://webpack.js.org), trying to make its config file work, looking for appropriate\nplugins. At some point the maintainers became convinced that the required use of `webpack` in\nSwiftWasm projects could limit the wider adoption of SwiftWasm itself. Hopefully, with `carton` you\ncan avoid using `webpack` altogether. `carton` also simplifies a few other things in your SwiftWasm\ndevelopment workflow such as toolchain and SDK installations.\n\n## Getting started\n\n### Requirements\n\n- Xcode 15.1 or later.\n- [Swift 5.9.2 or later](https://swift.org/download/).\n\n### Installation\n\nTo install `carton` as a SwiftPM plugin, first add the following line to your `Package.swift` file:\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/swiftwasm/carton\", from: \"1.0.0\"),\n],\n```\n\n\u003e [!WARNING]\n\u003e - If you already use `carton` before 0.x.x versions via Homebrew, you can remove it with `brew uninstall carton` and install the new version as a SwiftPM dependency.\n\u003e - Also please remove the old `.build` directory before using the new `carton`\n\n### Usage\n\nThe `swift run carton dev` command builds your project with the SwiftWasm toolchain and starts an HTTP server\nthat hosts your WebAssembly executable and a corresponding JavaScript entrypoint that loads it. The\napp, reachable at [http://127.0.0.1:8080/](http://127.0.0.1:8080/), will automatically open in your\ndefault web browser. The port that the development server uses can also be controlled with the\n`--port` option (or `-p` for short). You can edit the app source code in your favorite editor and\nsave it, `carton` will immediately rebuild the app and reload all browser tabs that have the app\nopen. You can also pass a `--verbose` flag to keep the build process output available, otherwise\nstale output is cleaned up from your terminal screen by default. If you have a custom `index.html`\npage you'd like to use when serving, pass a path to it with a `--custom-index-page` option.\n\nThe `swift run carton test` command runs your test suite in [`wasmer`](https://wasmer.io/), [`node`](https://nodejs.org/en/)\nor using your default browser. You can switch between these with the `--environment` option, passing\neither: `command`, `node` or `browser`. Code that depends on\n[JavaScriptKit](https://github.com/swiftwasm/JavaScriptKit) should pass either `--environment node` or\n`--environment browser` options, depending on whether it needs Web APIs to work. Otherwise\nthe test run will not succeed, since JavaScript environment is not available with `--environment command`.\nIf you want to run your test suite on CI or without GUI but on browser, you can pass `--headless` flag.\nIt enables [WebDriver](https://w3c.github.io/webdriver/)-based headless browser testing. Note that you\nneed to install a WebDriver executable in `PATH` before running tests.\nYou can use the command with a prebuilt test bundle binary instead of building it in carton by passing\n`--prebuilt-test-bundle-path \u003cyour binary path\u003e`.\n\nThe `swift run carton bundle` command builds your project using the `release` configuration (although you can\npass the `--debug` flag to it to change that), and copies all required assets to the `Bundle`\ndirectory. You can then use a static file hosting (e.g. [GitHub Pages](https://pages.github.com/))\nor any other server with support for static files to deploy your application. All resulting bundle\nfiles except `index.html` are named by their content hashes to enable [cache\nbusting](https://www.keycdn.com/support/what-is-cache-busting). As with `swift run carton dev`, a custom\n`index.html` page can be provided through the `--custom-index-page` option. You can also pass\n`--debug-info` flag to preserve `names` and DWARF sections in the resulting `.wasm` file, as these\nare stripped in the `release` configuration by default. By default, `swift run carton bundle` will run `wasm-opt`\non the resulting .wasm binary in order to reduce its file size. That behaviour can be disabled (in order\nto speed up the build) by appending the `--wasm-optimizations none` option.\n\nAll commands that delegate to `swift build` and `swiftc` (namely, `dev`, `test`, and `bundle`)\ncan be passed `-Xswiftc` arguments, which is equivalent to `-Xswiftc` in `swift build`. All\n`-Xswiftc` arguments are propagated to `swiftc` itself unmodified.\n\nAll of these commands and subcommands can be passed a `--help` flag that prints usage info and\ninformation about all available options.\n\n## How does it work?\n\n`carton` bundles a [WASI](https://wasi.dev) polyfill, which is currently required to run any SwiftWasm code,\nand the [JavaScriptKit](https://github.com/kateinoigakukun/JavaScriptKit/) runtime for convenience.\n`carton` also embeds an HTTP server for previewing your SwiftWasm app directly in a browser.\nThe development version of the polyfill establishes a helper WebSocket connection to the server, so that\nit can reload development browser tabs when rebuilt binary is available. This brings the development\nexperience closer to Xcode live previews, which you may have previously used when developing SwiftUI apps.\n\n`carton` does not require any config files for these basic development scenarios, while some configuration\nmay be supported in the future, for example for complex asset pipelines if needed. The only requirement\nis that your `Package.swift` contains at least a single executable product, which then will be compiled\nfor WebAssembly and served when you start `swift run carton dev` in the directory where `Package.swift` is located.\n\n`carton` is built as a SwiftPM Plugin with [SwiftNIO](https://github.com/apple/swift-nio), and supports both\nmacOS and Linux. (Many thanks to everyone supporting and maintaining those projects!)\n\n\u003e [!TIP]\n\u003e There is no comprehensive documentation about the internal architecture of `carton`, but [this page](https://github.com/swiftwasm/carton/pull/420) might be helpful to understand the current architecture and rationale.\n\n### Running `swift run carton dev` with the `release` configuration\n\nBy default `swift run carton dev` will compile in the `debug` configuration. Add the `--release` flag to compile in the `release` configuration.\n\n### Version compatibility\n\n`carton` previously embedded runtime parts of [the JavaScriptKit library](https://github.com/swiftwasm/JavaScriptKit).\nThis runtime allows Swift and JavaScript code to interoperate in Node.js and browser environments. Because of how\nJavaScriptKit runtime was embedded, older versions of JavaScriptKit were incompatible with different versions of\n`carton` and vice versa. This incompatibility between different versions was resolved starting with JavaScriptKit 0.15\nand `carton` 0.15. All version combinations of `carton` and JavaScriptKit higher than those are compatible with each\nother.\n\nYou still have to keep in mind that older versions of SwiftWasm may be incompatible with newer `carton`. You can follow\nthe compatibility matrix if you need to use older versions:\n\n| `carton` version | SwiftWasm version | JavaScriptKit version | Tokamak version |\n| ---------------- | ----------------- | --------------------- | --------------- |\n| 1.0+             | 5.9.2             |                       |                 |\n| 0.20+            | 5.9               |                       |                 |\n| 0.15+            | 5.6               | 0.15+                 | 0.10.1+         |\n| 0.14             | 5.6               | 0.14                  | 0.10            |\n| 0.13             | 5.5               | 0.13                  | 0.9.1           |\n| 0.12.2           | 5.5               | 0.12                  | 0.9.1           |\n| 0.12.0           | 5.5               | 0.11                  | 0.9.0           |\n| 0.11.0           | 5.4               | 0.10.1                | 0.8.0           |\n\n## Contributing\n\n### Sponsorship\n\nIf this tool saved you any amount of time or money, please consider [sponsoring\nthe SwiftWasm organization](https://github.com/sponsors/swiftwasm). Or you can sponsor some of our\nmaintainers directly on their personal sponsorship pages:\n[@carson-katri](https://github.com/sponsors/carson-katri),\n[@kateinoigakukun](https://github.com/sponsors/kateinoigakukun), and\n[@MaxDesiatov](https://github.com/sponsors/MaxDesiatov). While some of the\nsponsorship tiers give you priority support or even consulting time, any amount is\nappreciated and helps in maintaining the project.\n\n[Become a gold or platinum sponsor](https://github.com/sponsors/swiftwasm/) and contact maintainers to add your logo on our README on GitHub with a link to your site.\n\n\u003ca href=\"https://www.emergetools.com/\"\u003e\n  \u003cimg src=\"https://github.com/swiftwasm/swift/raw/swiftwasm-distribution/assets/sponsors/emergetools.png\" width=\"30%\"\u003e\n\u003c/a\u003e\n\n### Coding Style\n\nThis project uses [SwiftFormat](https://github.com/nicklockwood/SwiftFormat)\nand [SwiftLint](https://github.com/realm/SwiftLint) to\nenforce formatting and coding style. We encourage you to run SwiftFormat within\na local clone of the repository in whatever way works best for you either\nmanually or automatically via an [Xcode\nextension](https://github.com/nicklockwood/SwiftFormat#xcode-source-editor-extension),\n[build phase](https://github.com/nicklockwood/SwiftFormat#xcode-build-phase) or\n[git pre-commit\nhook](https://github.com/nicklockwood/SwiftFormat#git-pre-commit-hook) etc.\n\nTo guarantee that these tools run before you commit your changes on macOS, you're encouraged\nto run this once to set up the [pre-commit](https://pre-commit.com/) hook:\n\n```\nbrew bundle # installs SwiftLint, SwiftFormat and pre-commit\npre-commit install # installs pre-commit hook to run checks before you commit\n```\n\nRefer to [the pre-commit documentation page](https://pre-commit.com/) for more details\nand installation instructions for other platforms.\n\nSwiftFormat and SwiftLint also run on CI for every PR and thus a CI build can\nfail with inconsistent formatting or style. We require CI builds to pass for all\nPRs before merging.\n\n### Code of Conduct\n\nThis project adheres to the [Contributor Covenant Code of\nConduct](https://github.com/swiftwasm/.github/blob/main/CODE_OF_CONDUCT.md).\nBy participating, you are expected to uphold this code. Please report\nunacceptable behavior to hello@swiftwasm.org.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswiftwasm%2Fcarton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswiftwasm%2Fcarton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswiftwasm%2Fcarton/lists"}