@tsmodule/tsmodule 40.0.5 → 40.0.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +57 -43
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -3,22 +3,23 @@
|
|
|
3
3
|
<h1>TypeScript Module Toolkit</h1>
|
|
4
4
|
</div>
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
tsmodule is a toolkit for developing **standardized, pure ESM TypeScript
|
|
7
|
+
modules** that target any platform.
|
|
7
8
|
|
|
8
9
|
**Table of contents**
|
|
9
10
|
|
|
10
11
|
<!-- toc -->
|
|
11
12
|
|
|
13
|
+
- [Installation](#installation)
|
|
14
|
+
* [Requirements (global)](#requirements-global)
|
|
15
|
+
* [Existing projects](#existing-projects)
|
|
16
|
+
* [New projects](#new-projects)
|
|
12
17
|
- [Purpose](#purpose)
|
|
13
18
|
* [Create ESM packages using TypeScript](#create-esm-packages-using-typescript)
|
|
14
19
|
* [Develop projects in real-time](#develop-projects-in-real-time)
|
|
15
20
|
* [Build to optimized ES modules](#build-to-optimized-es-modules)
|
|
16
|
-
|
|
21
|
+
* [Optimize NPM dependencies with `-b, --bundle`](#optimize-npm-dependencies-with--b---bundle)
|
|
17
22
|
* [Run TypeScript directly](#run-typescript-directly)
|
|
18
|
-
- [Installation](#installation)
|
|
19
|
-
+ [Requirements](#requirements)
|
|
20
|
-
+ [Existing projects](#existing-projects)
|
|
21
|
-
+ [New projects](#new-projects)
|
|
22
23
|
- [Use Cases](#use-cases)
|
|
23
24
|
* [Generic TypeScript library](#generic-typescript-library)
|
|
24
25
|
* [React component library (using Next.js)](#react-component-library-using-nextjs)
|
|
@@ -29,32 +30,64 @@ TSModule is a toolkit for developing pure ESM TypeScript packages that target an
|
|
|
29
30
|
|
|
30
31
|
<!-- tocstop -->
|
|
31
32
|
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
### Requirements (global)
|
|
36
|
+
|
|
37
|
+
- Node v14+ (for ESM support)
|
|
38
|
+
- Yarn (for `resolutions` package.json field)
|
|
39
|
+
|
|
40
|
+
### Existing projects
|
|
41
|
+
|
|
42
|
+
To convert an existing project (and install standardized package.json settings,
|
|
43
|
+
dependencies, and config files), run this in your project directory:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
tsmodule convert
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
<sub>You will need to move all TS source files to `src/` if they are not there
|
|
50
|
+
already. Ensure you read the [module
|
|
51
|
+
configuration notes](#module-configuration) regarding "index exports" as it
|
|
52
|
+
relates to importing downstream.</sub>
|
|
53
|
+
|
|
54
|
+
### New projects
|
|
55
|
+
|
|
56
|
+
Create a new package with:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
tsmodule create [--react] project-name
|
|
60
|
+
```
|
|
61
|
+
|
|
32
62
|
## Purpose
|
|
33
63
|
|
|
34
64
|
### Create ESM packages using TypeScript
|
|
35
65
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
66
|
+
`tsmodule create` exists to bootstrap a Node or React project in as little time
|
|
67
|
+
as possible. The created packages are modular, and `tsmodule create --react`
|
|
68
|
+
will create a modular Next.js project with [importable components and styles](#react-component-library-using-nextjs).
|
|
39
69
|
|
|
40
|
-
|
|
70
|
+
Ready out of the box:
|
|
41
71
|
|
|
42
72
|
- package.json scripts
|
|
43
|
-
- TypeScript, ESLint
|
|
73
|
+
- TypeScript, ESLint configs (Tailwind, PostCSS for React)
|
|
44
74
|
- CI/CD with GitHub Actions
|
|
45
75
|
|
|
46
76
|
### Develop projects in real-time
|
|
47
77
|
|
|
48
78
|
Build in dev mode and watch for changes:
|
|
49
79
|
|
|
50
|
-
```
|
|
51
|
-
|
|
80
|
+
```
|
|
81
|
+
tsmodule dev
|
|
52
82
|
```
|
|
53
83
|
|
|
54
84
|
### Build to optimized ES modules
|
|
55
85
|
|
|
56
|
-
|
|
57
|
-
|
|
86
|
+
Production builds are minified ESM, with support for `my-package/a/b/c` path
|
|
87
|
+
resolution (see [Module configuration](#module-configuration) below).
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
tsmodule build [--bundle]
|
|
58
91
|
```
|
|
59
92
|
|
|
60
93
|
**All projects:**
|
|
@@ -67,48 +100,29 @@ $ tsmodule build [--bundle]
|
|
|
67
100
|
- Bundle CSS by default
|
|
68
101
|
- Use Tailwind by default
|
|
69
102
|
|
|
70
|
-
|
|
103
|
+
### Optimize NPM dependencies with `-b, --bundle`
|
|
71
104
|
|
|
72
105
|
With `-b, --bundle` mode, all entry points are compiled "in-place" and runtime NPM dependencies will generally not be needed as they will be inlined. If you build in bundle mode, you can move your dependencies to devDependencies, as the only thing that will be needed to run any/all compiled-in-place entry point(s) in your module are the bundles themselves.
|
|
73
106
|
|
|
74
107
|
TSModule itself builds with `-b, --bundle` flag, and requires only two runtime NPM dependencies:
|
|
75
108
|
|
|
76
109
|
1. `esbuild`, which does the heavy lifting for the build process, does not allow itself to be bundled
|
|
77
|
-
2. `typescript`, so TSModule can use the built `tsc` binary to generate `.d.ts`
|
|
110
|
+
2. `typescript`, so TSModule can use the built `tsc` binary to generate `.d.ts`
|
|
111
|
+
type declarations during builds
|
|
112
|
+
|
|
113
|
+
<sub>Note: Bundling every entry point in place may not be what you want, i.e. if you
|
|
114
|
+
only have a single entrypoint. In these cases, `tsmodule build -b src/index.ts`
|
|
115
|
+
is more appropriate.</sub>
|
|
78
116
|
|
|
79
117
|
### Run TypeScript directly
|
|
80
118
|
|
|
81
|
-
```
|
|
82
|
-
|
|
119
|
+
```
|
|
120
|
+
tsmodule file.ts
|
|
83
121
|
```
|
|
84
122
|
|
|
85
123
|
- Uses Node module loader to resolve TS at runtime
|
|
86
124
|
- Executable TypeScript files with `#!/usr/bin/env tsmodule`
|
|
87
125
|
|
|
88
|
-
## Installation
|
|
89
|
-
|
|
90
|
-
### Requirements (global)
|
|
91
|
-
|
|
92
|
-
- Node v14+ (for ESM support)
|
|
93
|
-
- Yarn (for `resolutions` package.json field)
|
|
94
|
-
|
|
95
|
-
### Existing projects
|
|
96
|
-
|
|
97
|
-
To convert an existing project (and install standardized package.json settings,
|
|
98
|
-
dependencies, and config files), run this in your project directory:
|
|
99
|
-
|
|
100
|
-
```bash
|
|
101
|
-
tsmodule convert
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
**You will need to move all source files to `src/`. Ensure you read the [module
|
|
105
|
-
configuration notes](#module-configuration) regarding "index exports" as it
|
|
106
|
-
relates to importing downstream.**
|
|
107
|
-
|
|
108
|
-
### New projects
|
|
109
|
-
|
|
110
|
-
Use `tsmodule create [--react] project-name` to create a new project.
|
|
111
|
-
|
|
112
126
|
## Use Cases
|
|
113
127
|
|
|
114
128
|
Below are some example use cases of TS modules in practice.
|