st-start

2.0.0-beta.48 verified Sat Apr 25 auth: no javascript

An opinionated, zero-configuration TypeScript project bundler & starter for frontend and Node.js, version 2.0.0-beta.48. It wraps webpack and babel with stable plugins to provide fast builds, multi-threaded type checking, HMR, and code splitting. Supports modern CSS (PostCSS, LostGrid, SASS), CSS modules with types, ESM, and auto-polyfilling via Browserslist. Includes ESLint linting, .env support, gzip compression, and an HTML artifact graph analyzer. Differentiates from other bundlers by promising a minimal or no config file, focusing on TypeScript-first workflows, and emphasizing robustness and developer experience with clear error messages and desktop notifications. Released under the MIT license and maintained by the SpringType organization, it is part of a larger ecosystem but remains a standalone tool.

Common errors

error Cannot find module 'st-start' ↓

cause st-start is not installed or not in node_modules, or you tried to import it in code instead of running CLI.

fix

Ensure npm install -D st-start is run. Use npx st-start to execute CLI, not a require/import.

error You may need an appropriate loader to handle this file type ↓

cause st-start does not include a loader for certain file types (e.g., .vue, .svelte).

fix

st-start only supports TypeScript, JavaScript, CSS, SASS, and images. For other file types, you may need to extend the webpack config manually.

error TypeScript: Cannot use import statement outside a module ↓

cause Your tsconfig.json may not have 'module' set to 'ESNext' or 'CommonJS', or the file is not treated as a module.

fix

Ensure tsconfig.json has "module": "ESNext" for st-start's dynamic imports to work, or adjust your project structure.

Warnings

breaking st-start v2 is a complete rewrite over v1. Configuration options and CLI flags may have changed. ↓

fix Refer to the v2 documentation and update your st.config.js accordingly. Run `st-start -h` to see current CLI options.

deprecated ESM syntax in st.config.js is not supported; only CommonJS module.exports works. ↓

fix Use `module.exports = { ... }` instead of `export default { ... }`.

gotcha st-start does not support direct import/require of its internals. The package is a CLI tool; use it via command line, not as a library. ↓

fix Use `npx st-start` or run via npm scripts. Do not `import st-start` in your code.

gotcha The bundler uses webpack under the hood; advanced webpack customizations might conflict with st-start's presets. ↓

fix Avoid custom webpack configs; rely on st-start's configuration options (st.config.js). If you need deep customization, consider using webpack directly.

Install

npm install st-start

yarn add st-start

pnpm add st-start

Imports

st-start (CLI)
wrong
```
import st-start from 'st-start'
```
correct
```
npx st-start
```
st-start is a CLI tool; it should be invoked via `npx st-start` or as a script in package.json. Do not try to import it directly in code.
BuildConfig
wrong
```
const BuildConfig = require('st-start').BuildConfig
```
correct
```
import { BuildConfig } from 'st-start'
```
Since version 2, st-start is ESM-first. Use named imports from the package if you need config types.
st.config.js
wrong
```
export default { /* config */ }
```
correct
```
module.exports = { /* config */ }
```
The configuration file must be a CommonJS module (module.exports). ESM is not supported for st.config.js.

Quickstart

Sets up a new project with st-start: installs the bundler, creates package.json scripts, and shows minimal entry files (HTML and TSX) to get a dev server running.

// 1. Install st-start as a dev dependency
npm install -D st-start

// 2. Add scripts to package.json
{
  "scripts": {
    "start": "st-start",
    "build": "st-start -env production"
  }
}

// 3. Create src/index.html as entry HTML
// <!DOCTYPE html>
// <html>
// <head><title>My App</title></head>
// <body><div id="root"></div></body>
// </html>

// 4. Create src/index.tsx as entry TypeScript
// import React from 'react';
// import ReactDOM from 'react-dom';
// ReactDOM.render(<h1>Hello World</h1>, document.getElementById('root'));

// 5. Run the start script
npm run start