{"id":13660751,"url":"https://github.com/springtype-org/st-start","last_synced_at":"2025-04-24T23:30:40.421Z","repository":{"id":55555203,"uuid":"215427380","full_name":"springtype-org/st-start","owner":"springtype-org","description":"Zero configuration TypeScript/JavaScript bundler \u0026 DevServer for frontend and Node.js projects. Framework agnostic.","archived":true,"fork":false,"pushed_at":"2020-12-22T10:13:08.000Z","size":5490,"stargazers_count":2,"open_issues_count":13,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-10T15:44:12.321Z","etag":null,"topics":["babel","browserslist","bundler","cli","code-splitting","cross-platform","css","dev-server","hmr","html","javascript","jest","nodejs","postcss","pwa","sass","server","typescript","webpack","zero-configuration"],"latest_commit_sha":null,"homepage":"https://www.springtype.org","language":"TypeScript","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/springtype-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-16T01:13:32.000Z","updated_at":"2023-01-28T10:35:41.000Z","dependencies_parsed_at":"2022-08-15T03:10:27.348Z","dependency_job_id":null,"html_url":"https://github.com/springtype-org/st-start","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springtype-org%2Fst-start","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springtype-org%2Fst-start/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springtype-org%2Fst-start/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springtype-org%2Fst-start/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/springtype-org","download_url":"https://codeload.github.com/springtype-org/st-start/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250727441,"owners_count":21477316,"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":["babel","browserslist","bundler","cli","code-splitting","cross-platform","css","dev-server","hmr","html","javascript","jest","nodejs","postcss","pwa","sass","server","typescript","webpack","zero-configuration"],"created_at":"2024-08-02T05:01:25.345Z","updated_at":"2025-04-24T23:30:40.010Z","avatar_url":"https://github.com/springtype-org.png","language":"TypeScript","readme":"## `st-start`: The missing TypeScript bundler\n\n\u003e Zero configuration TypeScript bundler \u0026 DevServer for frontend and Node.js projects.\n\n`st-start` tries to make developing and bundling TypeScript projects so easy, even your cat could do it 😉\n\n\u003cimg src=\"cat.jpg\" width=\"250\"\u003e\n\nWhile developing SpringType, we've had headaches to find the right go-to bundler for TypeScript.\n\nWe thought, it shall be easy, but we've learned that we had to put together a lot of configuration to get where we wanted to be. *And too often, it just broke and we spent half of a day on StackOverflow* :-( \n\nWe just wanted:\n\n- TypeScript: All language features, no namespace issues, fast builds, multi-threaded type checking and dynamic code splitting with `import('...')`\n- Modern CSS: PostCSS, LostGrid, CSS modules (with types!) and SASS\n- Zero-config! Usually no config file needed. Assumes common sense: Entrypoint: `src/index.tsx?`, `dist` folder for output. `src/index.html` as input HTML.\n- Flexible: Everything it assumes should be changable using a config file like `st.config.js`\n- Simple configuration: If you need it, just set [easy options](https://github.com/springtype-org/st-start/blob/master/src/interface/ibuild-config.ts) and you get where you want to be\n- Robust: Uses webpack + babel but only stable, industry standard plugins. _It shall not break because you let the_ 🐶 _in._\n- Efficient: Chooses the best webpack + babel configuration for you (*trust us, we've done tons of painful research on it*). Inlines `\u003cstyle\u003e` and small images. Tree-shakes and uglifies with `Terser` but keeps class names for sanity. `gzips` all output. *Optional `brotli` compression support.*\n- Linting with ESLint and `.eslintrc.js` + auto-fixing code-style issues too\n- Backwards compatibility + auto-polyfilling with `.browserslistrc`\n- Transparent: It should give a deep insight in what and how it built the code for production (HTML artifact graph analyzer).\n- Environment-agnostic: `.env` support and it should replace `process.env.NODE_ENV` and `process.env.ST_*` in frontend code as well. In HTML you should be able to use `%NODE_ENV%` or `%PUBLIC_URL%` to resolve to the right places.\n- Developer Experience should be just amazing: Beautiful `console` and  in-browser overlay error messages with code frame highlighting and meaningful stack traces. And desktop notifications for typing errors.\n- Versatile: No limitations for frontend frameworks or Node.js as long as they are TypeScript/JavaScript based\n- Elegant: It should be fun to read the code as well! :)\n- Friendly: This bundler devotes to real-world needs. No paradigms should stand in the way of the  developer.\n\n\u003ch2 align=\"center\"\u003eSetup\u003c/h2\u003e\n\n    yarn add -D st-start\n\n\u003ch2 align=\"center\"\u003eHow to use?\u003c/h2\u003e\n\nCreate or extend the `scripts` entry in your `package.json`:\n\n```json\n{\n    \"scripts\": {\n        \"start:prod\": \"st-start -env production\",\n        \"start\": \"st-start\"\n    },\n}\n``` \n\n\u003e Oh, do you already know [the missing npm script runner](https://github.com/springtype-org/st-run)? It can help if you want to run more than one command in npm scripts or run them in parallel. Or run them npx-like. Or run a system command on any platform =)\n\n\u003ch2 align=\"center\"\u003eHow to customize?\u003c/h2\u003e\n\n`st-start` has a few command line parameters. Just run `st-start -h` to learn about them:\n\n\u003cimg width=\"500\" src=\"usage.png\"\u003e\n\nYou can set CLI arguments like: `st-start -env production` to set the production mode\nor set the `platform` to `nodejs` if you like to bundle a Node.js application.\n\nYou can also create file `st.config.js` to further specifiy the build configuration.\nIf this config file name doesn't work for you, you could say `st-start -c my-own-config.js` \nand the bundler would read this config file instead.\n\n\u003ch2 align=\"center\"\u003eEasy config file\u003c/h2\u003e\n\nIt is rather easy to configure rather complex build setups using `st-start`. But sure, we have many options.\n\nThat's why we put them together in just two simple  (but long =) files:\n\n- The [IBuildConfig](https://github.com/springtype-org/st-start/blob/master/src/interface/ibuild-config.ts) interface definition\n- The [defaults](https://github.com/springtype-org/st-start/blob/master/src/defaults.ts) definition\n\nThis way, you can easily find what's important to customize your builds and also know the default behaviour that `st-start` falls back to when you don't set the option.\n\nAll documentation is written in the interface definition code too. This makes sure that we never get out-of-sync with documentation and implementation.\n\nHere's an example `st.config.js` for a multi-target build:\n\n```js\nmodule.exports = [{\n    // builds a frontend app with an alternative \n    // entryPoint (default would be src/index.tsx or src/index.ts)\n    entryPoint: 'src/index-alt.tsx'\n}, {\n    // this builds a background script, \n    // e.g. for DevTools and bundles it all into one single file\n    entryPoint: 'src/background.ts',\n    singleFileOutput: 'dist/background.js'\n}, {\n    // here we bundle a Node.js application\n    isNodeJsTarget: true,\n    entryPoint: 'src/server.ts',\n    singleFileOutput: 'dist/server.js'\n}];\n```\n\nAs you can see, we've put great effort in naming the options intuitively. \n\nThe context path (the directory `st-start` operates in) is always the directory you start `st-start` in.\n\nSo all paths you name in the config should be either absolute paths or relative to the context path.\n\n\u003ch2 align=\"center\"\u003eA note on Node.js\u003c/h2\u003e\n\nNode.js doesn't usually know how to handle Source Maps. \n\nSo when you bundle a server application using `st-start`,\nand there is an error or you want to debug it, it's better to tell node to show you the original code instead of the optimzed, transpiled one.\n\nFor that, just install:\n\n    yarn add -D source-map-support\n\nAnd run `node` like this:\n\n    node -r source-map-support/register dist/yourNodeScript.js\n\n\u003ch2 align=\"center\"\u003eBuild and Test\u003c/h2\u003e\n\nEspecially if you contributed to this project, you'd like to build and test it to make sure everything works fine, before you open a Pull Request (PR) :-)\n\nSo in a shell, please run:\n\n    # install the dependencies\n    yarn\n\n    # transpile the code, copy files over to ./dist\n    yarn build\n\n    # run unit \u0026 end-to-end tests\n    yarn test\n\n\n\u003ch2 align=\"center\"\u003eOur Motivation\u003c/h2\u003e\n\nYou may ask: *\"Why do we need another bundler?\"* We've asked us the same question. \n\nWe really didn't wanted to develop `st-start`. It was a lot of work and it wasn't fun all the time. However, we felt like we had no other choice. Why?\n\n`TL;DR:`\n\n*We wanted an easy to use TypeScript bundler that could do everything `create-react-app` could do and on top of that a little bit more. We wanted this bundler to be framework agnostic: But there was none*.\n\nWe've tried many different solutions over the course of one year of framework development: \n- webpack/babel custom config per project\n- create-react-app\n- Parcel\n- Rollup \n- FuseBox\n\n...but, no matter the amazing features, the amazing teams and amazing solutions they hard, when it came to our needs, they all had limitations that eventually clashed with some paradigms and it led to one or more limitations that we couldn't overcome:\n\n- Complexity in configuration\n- Inflexibility in zero-configuration setups\n- Fragility in less usual setups\n- Platform-dependence\n- Framework-dependence\n\nWe needed a solution for the users of SpringType, which is just easy ot use and *just works fine in all cases*. SpringType uses TypeScript primarily and there was no TypeScript-first bundler that would give us, what we wanted.\n\nThe compromise was to develop a simple to use, multi-target TypeScript build system that would use industry standard projects and glue them together in a smart way and so, `st-start` was born.\n\nHowever, this is not the end of the story. *We have big plans! :-)*\n\n\u003ch2 align=\"center\"\u003eOur Vision\u003c/h2\u003e\n\nAt the time being, this project is what we have and it works really well. However, we're less happy with the \ntranspilation performance. Parsing, type-checking and transpiling TypeScript takes a toll on performance atm.\n\nSo we came to the conclusion that at one time in the future we want to come up with a new transpiler architecture\nand replace babel and webpack.\n\nHowever, the configuration API will remain the same because the interface is designed agnostic to the implementations used *and we love API stability.*\n\n\n\u003ch2 align=\"center\"\u003eShort-term Roadmap\u003c/h2\u003e\n\nWe're keen to improve this implementation until we feel really comfortable with it. Right now this lacks:\n\n- [ ] Many e2e tests\n- [ ] Almost all unit tests\n- [ ] A refactoring towards a more modular, functional code base. We want smaller functions which are better to test and a better domain-driven grouping of features\n- [ ] Some defaults are still hard-coded and should become config options\n- [ ] We need your input about what to improve next. Please file an issue if you find something counter-intuitive or buggy.\n\n\u003ch2 align=\"center\"\u003eMaintainers\u003c/h2\u003e\n\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cimg width=\"150\" height=\"150\"\n        src=\"https://avatars3.githubusercontent.com/u/454817?v=4\u0026s=150\"\u003e\n        \u003c/br\u003e\n        \u003ca href=\"https://github.com/kyr0\"\u003eAron Homberg\u003c/a\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cimg width=\"150\" height=\"150\"\n        src=\"https://avatars2.githubusercontent.com/u/12079044?s=150\u0026v=4\"\u003e\n        \u003c/br\u003e\n        \u003ca href=\"https://github.com/mansi1\"\u003eMichael Mannseicher\u003c/a\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003ctbody\u003e\n\u003c/table\u003e\n\n\u003ch2 align=\"center\"\u003eContributing\u003c/h2\u003e\n\nPlease help out to make this project even better and see your name added to the list of our  \n[CONTRIBUTORS.md](./CONTRIBUTORS.md) :tada:","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspringtype-org%2Fst-start","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspringtype-org%2Fst-start","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspringtype-org%2Fst-start/lists"}