{"id":15685577,"url":"https://github.com/ptrdom/scalajs-esbuild","last_synced_at":"2025-04-30T14:41:01.163Z","repository":{"id":94132973,"uuid":"598748193","full_name":"ptrdom/scalajs-esbuild","owner":"ptrdom","description":"Bundles Scala.js projects and their npm dependencies with esbuild","archived":false,"fork":false,"pushed_at":"2025-04-29T02:32:06.000Z","size":841,"stargazers_count":14,"open_issues_count":8,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-29T03:41:27.638Z","etag":null,"topics":["esbuild","npm","scala-js"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ptrdom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-02-07T18:25:51.000Z","updated_at":"2025-04-27T02:05:15.000Z","dependencies_parsed_at":"2023-03-13T17:06:22.626Z","dependency_job_id":"359a27cc-e071-4232-acc5-19af974e3772","html_url":"https://github.com/ptrdom/scalajs-esbuild","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptrdom%2Fscalajs-esbuild","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptrdom%2Fscalajs-esbuild/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptrdom%2Fscalajs-esbuild/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptrdom%2Fscalajs-esbuild/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ptrdom","download_url":"https://codeload.github.com/ptrdom/scalajs-esbuild/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251722799,"owners_count":21633016,"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":["esbuild","npm","scala-js"],"created_at":"2024-10-03T17:27:05.123Z","updated_at":"2025-04-30T14:41:01.128Z","avatar_url":"https://github.com/ptrdom.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# scalajs-esbuild\n\nscalajs-esbuild is a module bundler for Scala.js projects that use npm packages: it bundles the .js files emitted by the\nScala.js compiler with their npm dependencies into a single .js file using [esbuild](https://esbuild.github.io/).\n\n[![sbt-scalajs-esbuild Scala version support](https://index.scala-lang.org/ptrdom/scalajs-esbuild/sbt-scalajs-esbuild/latest.svg)](https://index.scala-lang.org/ptrdom/scalajs-esbuild/sbt-scalajs-esbuild)\n\n## Getting started\n\nPlugin should feel quite familiar to the users of well known [scalajs-bundler](https://scalacenter.github.io/scalajs-bundler),\nwith the main difference being that there is no special handling of `npmDependencies` - they must be provided through\n`package.json` placed within `esbuild` directory in project's base.\n\nImplementation intentionally exposes only a few settings for configuration - provided scripts should be enough to get started with typical projects,\nbut any advanced configuration should be provided by modifying said scripts through their sbt settings - `esbuildBundleScript` and `esbuildServeScript`.\n\nAll sbt tasks that depend on Scala.js stages can be scoped both implicitly and explicitly, for example `esbuildBundle` will use `scalaJSStage` or the stage\ncan be provided within the command - `fastLinkJS/esbuildBundle`/`fullLinkJS/esbuildBundle`.\n\nComparing to [scalajs-vite](https://github.com/ptrdom/scalajs-vite), the main difference comes from the fact that [Vite](https://vitejs.dev/) is not a bundler, \nit is a build tool - it uses esbuild in dev server implementation and [Rollup](https://rollupjs.org/) for production bundles. Rollup is a \nsignificantly slower bundler than esbuild while also having no concept of development bundles. Development bundles must both \nbehave the same as production bundles and be fast to produce - the latter partially because they are missing optimisations important only in production. \nBecause in Scala.js projects these development bundles are actually very useful in certain workflows, particularly in the implementation of tests, \nscalajs-esbuild brings esbuild's performance into every aspect of Scala.js development workflow.\n\n### Base plugin\n\nBase plugin is designed for Node or browser libraries, CLIs or standalone scripts - for web apps please use [web plugin](#web-plugin).\n\n#### Basic setup\n\n1. Setup project layout, following is a minimal example:\n\n   ```\n   src\n     main\n      scala\n        example\n          Main.scala # Scala.js entry point\n   esbuild\n     package.json # devDependencies must provide esbuild package\n   ```\n\n1. Add plugin to sbt project:\n\n   ```scala\n   addSbtPlugin(\"me.ptrdom\" % \"sbt-scalajs-esbuild\" % pluginVersion)\n   ```\n\n1. Enable plugin in `build.sbt`:\n\n   ```\n   enablePlugins(ScalaJSEsbuildPlugin)\n   ```\n\n1. Specify that Scala.js project is an application with an entry point:\n\n   ```\n   scalaJSUseMainModuleInitializer := true\n   ```\n\n1. Use sbt tasks to compile Scala.js code and run esbuild:\n   - `esbuildBundle`\n     - Bundles are produced in `/target/${scalaVersion}/esbuild/main/out` directory.\n   - `run`/`test`\n     - `esbuildBundle` output will be fed to `jsEnvInput`.\n\nSee [examples](sbt-scalajs-esbuild/examples) for project templates.\n\n### Web plugin\n\nWeb plugin is designed for web apps. Because esbuild does not have a full-fledged build-in dev server and HTML entry point \ntransformations like Vite, this plugin attempts to provide good enough stand-ins to enable typical workflows.\n\n#### Basic setup\n\n1. Setup project layout, following is a minimal example:\n\n   ```\n   src\n     main\n      scala\n        example\n          Main.scala # Scala.js entry point\n   esbuild\n     index.html # esbuild HTML entry point\n     package.json # devDependencies must provide esbuild and parse5 packages\n   ```\n\n1. Add plugin to sbt project:\n\n   ```scala\n   addSbtPlugin(\"me.ptrdom\" % \"sbt-scalajs-esbuild-web\" % pluginVersion)\n   ```\n\n1. Enable plugin in `build.sbt`:\n\n   ```scala\n   enablePlugins(ScalaJSEsbuildWebPlugin)\n   ```\n\n1. Specify that Scala.js project is an application with an entry point:\n\n   ```scala\n   scalaJSUseMainModuleInitializer := true\n   ```\n\n   Such configuration would allow `main.js` bundle to be used in esbuild HTML entry point:\n\n   ```html\n   \u003cscript src=\"/main.js\"\u003e\u003c/script\u003e\n   ```\n\n   Entry points can be configured with `esbuildBundleHtmlEntryPoints` setting.\n\n1. Use sbt tasks to compile Scala.js code and run esbuild:\n    - `esbuildBundle`\n      - In addition to base plugin behavior, web implementation also does HTML entry point transformation - injection Scala.js entry points and CSS files into HTML.\n    - `~esbuildServe`\n       - Starts dev server on port `3000`.\n         - Port can be configured with `esbuildServe / serverPort` setting.\n      - Watches for updates to Scala.js code and any resources in `esbuild` directory.\n      - CSS can be hot reloaded, changes to Scala.js code will cause a page reload.\n    - `esbuildServeStart;~esbuildStage;esbuildServeStop`\n      - Starting of dev server and watching of sources can be done in separate commands too.\n\nSee [examples](sbt-scalajs-esbuild-web/examples) for project templates.\n\n### Electron plugin\n\nElectron plugin is designed to enable [Electron](https://www.electronjs.org/) app development with Scala.js. Besides\nbundling for tests and production builds, the plugin also provides a dev server implementation.\n\n#### Basic setup\n\n1. Setup project layout, following is a minimal example:\n\n   ```\n   src\n     main\n      scala\n        example\n          Main.scala # main process\n          Preload.scala # preload script\n          Renderer.scala # renderer process\n   esbuild\n     index.html # esbuild HTML entry point\n     package.json # devDependencies must provide esbuild, parse5 and electron packages\n   ```\n\n1. Add plugin to sbt project:\n\n   ```scala\n   addSbtPlugin(\"me.ptrdom\" % \"sbt-scalajs-esbuild-electron\" % pluginVersion)\n   ```\n\n1. Enable plugin in `build.sbt`:\n\n   ```scala\n   enablePlugins(ScalaJSEsbuildElectronPlugin)\n   ```\n\n1. Configure Scala.js entry points and Electron process model components:\n\n   ```scala\n   scalaJSModuleInitializers := Seq(\n     ModuleInitializer\n       .mainMethodWithArgs(\"example.Main\", \"main\")\n       .withModuleID(\"main\"),\n     ModuleInitializer\n       .mainMethodWithArgs(\"example.Preload\", \"main\")\n       .withModuleID(\"preload\"),\n     ModuleInitializer\n       .mainMethodWithArgs(\"example.Renderer\", \"main\")\n       .withModuleID(\"renderer\")\n   )\n   \n   Compile / esbuildElectronProcessConfiguration := new EsbuildElectronProcessConfiguration(\n     \"main\",\n     Set(\"preload\"),\n     Set(\"renderer\")\n   )   \n   ```\n\n   Such configuration would allow `renderer.js` bundle to be used in esbuild HTML entry point:\n\n   ```html\n   \u003cscript src=\"./renderer.js\"\u003e\u003c/script\u003e\n   ```\n\n   Entry points can be configured with `esbuildBundleHtmlEntryPoints` setting.\n\n1. Use web plugin sbt tasks to compile Scala.js code and run esbuild.\n\nSee [examples](sbt-scalajs-esbuild-electron/examples) for project templates.\n\n### Integrating with sbt-web\n\n1. Add plugin to sbt project:\n\n   ```scala\n   addSbtPlugin(\"me.ptrdom\" % \"sbt-web-scalajs-esbuild\" % pluginVersion)\n   ```\n\n1. Enable plugin in `build.sbt`:\n\n   ```scala\n   lazy val server = project\n     .settings(\n       scalaJSProjects := Seq(client),\n       pipelineStages := Seq(scalaJSPipeline)\n     )\n     .enablePlugins(SbtWebScalaJSEsbuildPlugin)\n    \n   lazy val client = project.enablePlugins(ScalaJSEsbuildPlugin)\n   ```\n\nSee [examples](sbt-web-scalajs-esbuild/examples) for project templates.\n\n## Package managers\n\nPlugins use [npm](https://www.npmjs.com/) by default, but provided `PackageManager` abstraction allows configuration of other\npackage managers.\n\n```scala\n// for yarn\nesbuildPackageManager := new PackageManager {\n  override def name = \"yarn\"\n  override def lockFile = \"yarn.lock\"\n  override def installCommand = \"install\"\n}\n\n// for pnpm\nesbuildPackageManager := new PackageManager {\n  override def name = \"pnpm\"\n  override def lockFile = \"pnpm-lock.yaml\"\n  override def installCommand = \"install\"\n}\n```\n\n## License\n\nThis software is licensed under the MIT license\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fptrdom%2Fscalajs-esbuild","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fptrdom%2Fscalajs-esbuild","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fptrdom%2Fscalajs-esbuild/lists"}