Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sinclairzx81/typescript-bundle
A Bundling Tool for TypeScript
https://github.com/sinclairzx81/typescript-bundle
assets bundle tooling typescript
Last synced: 4 days ago
JSON representation
A Bundling Tool for TypeScript
- Host: GitHub
- URL: https://github.com/sinclairzx81/typescript-bundle
- Owner: sinclairzx81
- License: mit
- Created: 2016-10-25T12:30:13.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2022-06-23T10:49:23.000Z (over 2 years ago)
- Last Synced: 2024-10-19T11:12:13.393Z (3 months ago)
- Topics: assets, bundle, tooling, typescript
- Language: TypeScript
- Homepage:
- Size: 219 KB
- Stars: 125
- Watchers: 8
- Forks: 5
- Open Issues: 11
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
- awesome-github-star - typescript-bundle
README
# TypeScript-Bundle
A bundling tool for TypeScript.
[](https://www.npmjs.com/package/typescript-bundle) [](https://travis-ci.org/sinclairzx81/typescript-bundle)
```bash
$ npm install typescript-bundle -g
```
```bash
$ tsc-bundle ./index.ts
```
## Overview
TypeScript-Bundle is a build tool for the TypeScript programming language. It layers the TypeScript compiler cli to enable direct bundling of modular TypeScript source code for immediate consumption in a browser.
This tool provides:
- The ability to bundle directly from `.ts`, `.tsx` or `tsconfig.json`.
- The ability to embed `text`, `json`, `base64` and `buffer` assets as modules.
- Support for custom pre-processing pipelines.
- Supports TypeScript compiler versions as low as 1.8.0.
This tool is offered as is for anyone who finds it useful.
## Docs
- [Options](#Options)
- [Usage](#Usage)
- [Assets](#Assets)
- [ExportAs](#ExportAs)
- [ImportAs](#ImportAs)
- [EntryPoint](#EntryPoint)
- [Transforms](#Transforms)
- [Tasks](#Tasks)
```
$ tsc-bundle script.ts | script.tsx | tsconfig.json
Examples: tsc-bundle index.ts
tsc-bundle tsconfig.json
tsc-bundle script.ts --exportAs Foo
tsc-bundle index.ts --outFile bundle.js
tsc-bundle index.ts --transform script.js
Options:
--outFile Outputs the bundle with the give filepath.
--target Sets the ES Target for the bundle.
--exportAs Exports bundle exports as a global variable.
--importAs Imports global variable as a module (namespace).
--importAsDefault Imports global variable as a module (default).
--entryPoint Overrides the default entry point for the bundle.
--transform Applies a transform to the bundle.
--watch Starts the compiler in watch mode.
--debug Prints debug information.
```
### Bundle from source file
Point TypeScript-Bundle at a TypeScript source file to have it bundle that file and everything it imports. Will use the default compiler settings.
```bash
# output: ./script.js
$ tsc-bundle ./script.ts
# output: ./bundle.js
$ tsc-bundle ./script.ts --outFile ./bundle.js
```
### Bundle from tsconfig.json
Point TypeScript-Bundle at a `tsconfig.json` to have it use the compiler settings within.
```json
{
"compilerOptions": {
"strict": true,
"target": "esnext",
"lib": ["dom", "esnext"],
},
"files": ["script.ts"]
}
```
```bash
$ tsc-bundle ./src/tsconfig.json
# output: ./script.js
```
```bash
$ tsc-bundle ./src/tsconfig.json --outFile ./bundle.js
# output: ./bundle.js
```
## Assets
##### Supported for TypeScript compiler versions 2.2.0 and higher.
```typescript
import Content from 'text!./file.txt'
```
TypeScript-Bundle automatically bundles files with a special import scheme similar to WebPack's [ts-loader](https://github.com/TypeStrong/ts-loader). It supports `text`, `json`, `base64`, `buffer` and `css` directives that inform the bundler how to embed the asset.
```typescript
import Text from 'text!./file.txt' // as 'string'
import Base64 from 'base64!./image.png' // as 'string | base64 encoded'
import Obj from 'json!./file.json' // as 'any'
import Buf from 'buffer!./file.dat' // as 'Uint8Array'
import Css from 'css!./file.css' // as 'string | @import concat'
```
### Declarations
To import assets without compiler warnings, TypeScript requires you define an additional declaration file `.d.ts` that describes the `file extension` to `type` mappings. The following is an example of such a declaration.
```typescript
declare module '*.txt' {
const value: string
export default value
}
declare module '*.json' {
const value: any
export default value
}
declare module '*.b64' {
const value: string
export default value
}
declare module '*.buf' {
const value: Uint8Array
export default value
}
declare module '*.css' {
const value: string
export default value
}
```
You can either add this declaration to your `tsconfig.json` or as a `/// ` directive if bundling from script.
## ExportAs
```
--exportAs GLOBAL
```
Assigns a global variable name to the bundle.
### Example
```TypeScript
// script.ts
export function add(a: number, b: number) { return a + b }
```
```bash
$ tsc-bundle script.ts --exportAs Foo
```
```javascript
var Foo = (function() { /* bundled code here */ })()
```
Now available to the page.
```html
console.log(Foo.add(10, 20))
```
### CommonJS
If you are bundling for nodejs, you can pass `--exportAs commonjs` that will make the bundle a nodejs module. Useful for keeping the internals of the bundle private while exposing a surface level API.
```bash
$ tsc-bundle ./script.ts --exportAs commonjs
```
```javascript
module.exports = (function() { /* bundled code here */ })()
```
```javascript
// node: app.js
const Foo = require('./script')
```
## ImportAs
```
--importAs GLOBAL=module
--importAsDefault GLOBAL=module
```
Adds global variables (such as those added to a web page when loading scripts via CDN) as internal modules.
### Import React
```bash
# install react declaration files.
$ npm install @types/react
$ npm install @types/react-dom
```
```TypeScript
// index.ts
import * as React from 'react'
import * as ReactDOM from 'react-dom'
```
```bash
# bundle with --importAs. The convention is GLOBAL_NAME=MODULE_NAME.
$ tsc-bundle index.ts --importAs React=react --importAs ReactDOM=react-dom
```
```html
```
It is possible to import as many global names as necessary.
### importAs vs importAsDefault
TypeScript-Bundle provides two importAs schemes for importing global variables. The decision to select one over the other is purely down to the import semantics provided by `@types/*` declaration for that library.
#### importAs
```
--importAs THREE=three
```
```typescript
import * as THREE from 'three'
```
#### importAsDefault
```
--importAsDefault THREE=three
```
```typescript
import THREE from 'three'
```
Select the most appropriate based on the library you're importing.
```
--entryPoint index2
```
Will override the default entry point for the bundle. By default, the last module within the bundle is treated as the default entry point and will be evaluated first. If this is undesirable, the `--entryPoint` option allows for the selection of any other module located within the bundle to be evaluated first. Useful when compiling with `glob` patterns such as `"include": [ "src/**/*" ]`.
## Transforms
```
--transform ./preprocessor.js
```
Allows for custom preprocessing of the bundle.
```javascript
// ./preprocessor.js
// run on typescript AMD output.
module.exports.typescriptOutput = function(javascript_code) {
// apply transformations here.
return javascript_code
}
// run on typescript-bundle output.
module.exports.bundleOutput = function(javascript_code) {
// apply transformations here.
return javascript_code
}
```
Multiple preprocessing stages can be stacked if required.
```
$ tsc-bundle ./index.ts --transform ./a.js --transform ./b.js --transform ./c.js
```
## Tasks
The following tasks are provided by this project.
```bash
$ npm run clean # cleans this project.
$ npm run amd-loaders # rebuilds es loader templates.
$ npm run build # builds the bundler.
$ npm run pack # packs the bundler.
$ npm run spec # builds and runs the spec project.
$ npm run install-cli # installs the bundler cli globally.
```