@nikovirtala/projen-constructs 0.4.1 → 0.5.1
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/.jsii +3 -3
- package/README.md +44 -8
- package/docs/api/assets/highlight.css +6 -6
- package/docs/api/functions/applyDefaults.html +2 -2
- package/docs/api/index.html +76 -33
- package/docs/api/interfaces/AwsCdkConstructLibraryProjectOptions.html +27 -27
- package/docs/api/interfaces/AwsCdkTypeScriptAppProjectOptions.html +29 -29
- package/docs/api/interfaces/JsiiProjectOptions.html +26 -26
- package/docs/api/interfaces/LocalStackOptions.html +2 -2
- package/docs/api/interfaces/ProjectGeneratorOptions.html +3 -3
- package/docs/api/interfaces/TypeScriptProjectOptions.html +24 -24
- package/docs/api/interfaces/VitestConfigOptions.html +2 -2
- package/lib/components/bundle-lambda-function-code.js +3 -3
- package/lib/components/colima.js +1 -1
- package/lib/components/homebrew.js +1 -1
- package/lib/components/lambda-function-construct-generator.js +1 -1
- package/lib/components/localstack.js +1 -1
- package/lib/components/mise.js +1 -1
- package/lib/components/typedoc.js +1 -1
- package/lib/components/vitest.js +1 -1
- package/lib/config.js +23 -6
- package/lib/native-typescript.d.ts +22 -0
- package/lib/native-typescript.js +77 -0
- package/lib/project-generator.js +1 -1
- package/lib/projects/awscdk-construct-library.generated.js +1 -1
- package/lib/projects/awscdk-typescript-app.generated.js +1 -1
- package/lib/projects/jsii.generated.js +1 -1
- package/lib/projects/typescript.generated.js +1 -1
- package/package.json +1 -1
package/docs/api/index.html
CHANGED
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
<pre><code class="bash"><span class="hl-0">pnpm</span><span class="hl-1"> </span><span class="hl-2">add</span><span class="hl-1"> </span><span class="hl-3">-D</span><span class="hl-1"> </span><span class="hl-2">@nikovirtala/projen-constructs</span><span class="hl-1"> </span><span class="hl-2">projen</span><span class="hl-1"> </span><span class="hl-2">constructs</span>
|
|
15
15
|
</code><button type="button">Copy</button></pre>
|
|
16
16
|
|
|
17
|
-
<p>Requires pnpm 12 and <code>projen</code>
|
|
17
|
+
<p>Requires pnpm 12 and <code>projen</code> ^0.104.23. <code>@mrgrain/cdk-esbuild</code> and <code>constructs</code> are peer
|
|
18
18
|
dependencies as well.</p>
|
|
19
19
|
<p>To create a project from scratch:</p>
|
|
20
20
|
<pre><code class="bash"><span class="hl-0">pnpm</span><span class="hl-1"> </span><span class="hl-2">dlx</span><span class="hl-1"> </span><span class="hl-2">projen</span><span class="hl-1"> </span><span class="hl-2">new</span><span class="hl-1"> </span><span class="hl-3">--from</span><span class="hl-1"> </span><span class="hl-2">@nikovirtala/projen-constructs</span><span class="hl-1"> </span><span class="hl-2">aws_cdk_construct_library</span>
|
|
@@ -88,9 +88,33 @@ rule set, so it only carries compiler options jsii accepts.</li>
|
|
|
88
88
|
the editor use, and the one <code>tsconfigDev</code> points at.</li>
|
|
89
89
|
<li><code>projenrc/tsconfig.json</code> covers <code>.projenrc.ts</code>.</li>
|
|
90
90
|
</ul>
|
|
91
|
+
<h3 id="native-typescript" class="tsd-anchor-link">Native TypeScript<a href="#native-typescript" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
|
|
92
|
+
<p>TypeScript and AWS CDK app projects run TypeScript with Node.js's built-in
|
|
93
|
+
<a href="https://nodejs.org/api/typescript.html#type-stripping">type stripping</a> instead of <code>tsx</code> or
|
|
94
|
+
<code>ts-node</code>: the default task is <code>node .projenrc.ts</code>, and the cdk.json <code>app</code> is <code>node src/main.ts</code>.
|
|
95
|
+
Their <code>tsconfig.json</code> sets <code>erasableSyntaxOnly</code> and <code>verbatimModuleSyntax</code>, so <code>tsc</code> reports code
|
|
96
|
+
that Node.js can't run before Node.js does.</p>
|
|
97
|
+
<p>Code in these projects must therefore:</p>
|
|
98
|
+
<ul>
|
|
99
|
+
<li>only use syntax that can be stripped: no <code>enum</code>s (use an <code>as const</code> object), no namespaces with
|
|
100
|
+
values, and no constructor parameter properties</li>
|
|
101
|
+
<li>mark type-only imports with <code>type</code> (Biome's <code>useImportType</code> fixes these)</li>
|
|
102
|
+
<li>import relative files with their <code>.ts</code> extension, and never import a directory</li>
|
|
103
|
+
<li>use Node.js <a href="https://nodejs.org/api/packages.html#subpath-imports">subpath imports</a>
|
|
104
|
+
(<code>#stacks</code> in <code>package.json</code> <code>imports</code>) instead of tsconfig <code>paths</code>, which Node.js doesn't read</li>
|
|
105
|
+
<li>import packages without an <code>exports</code> map either from the package root or with an explicit file,
|
|
106
|
+
e.g. <code>projen/lib/component.js</code> rather than <code>projen/lib/component</code></li>
|
|
107
|
+
</ul>
|
|
108
|
+
<p>Lambda handlers bundled by esbuild and tests run by Vitest aren't run by Node.js directly, but the
|
|
109
|
+
same compiler options apply to them.</p>
|
|
110
|
+
<p>JSII and AWS CDK construct library projects keep using <code>tsx</code>, because jsii compiles to CommonJS, and
|
|
111
|
+
their <code>.projenrc.ts</code> often imports their own <code>src</code>.</p>
|
|
112
|
+
<p>When you start a new project by hand, make sure <code>package.json</code> has <code>"type": "module"</code> before the
|
|
113
|
+
first <code>node .projenrc.ts</code>: <code>npm init</code> writes <code>"type": "commonjs"</code>, which makes Node.js reject the
|
|
114
|
+
<code>import</code> statements in <code>.projenrc.ts</code>.</p>
|
|
91
115
|
<h2 id="customization" class="tsd-anchor-link">Customization<a href="#customization" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
|
|
92
116
|
<p>Override any option by passing it to the constructor:</p>
|
|
93
|
-
<pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-
|
|
117
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">JsiiProject</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">project</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">JsiiProject</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-5">name:</span><span class="hl-1"> </span><span class="hl-2">"my-project"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">repositoryUrl:</span><span class="hl-1"> </span><span class="hl-2">"https://github.com/nikovirtala/my-project.git"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">minNodeVersion:</span><span class="hl-1"> </span><span class="hl-2">"26.0.0"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">author:</span><span class="hl-1"> </span><span class="hl-2">"Custom Author"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">authorAddress:</span><span class="hl-1"> </span><span class="hl-2">"custom@example.com"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">mise:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">vitest:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">tsconfig:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">compilerOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">noUnusedLocals:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">,</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-5">biomeOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">biomeConfig:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">formatter:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">lineWidth:</span><span class="hl-1"> </span><span class="hl-7">100</span><span class="hl-1">,</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> },</span><br/><span class="hl-1">});</span>
|
|
94
118
|
</code><button type="button">Copy</button></pre>
|
|
95
119
|
|
|
96
120
|
<p>Every component is exposed as an enable flag (<code>mise</code>, <code>vitest</code>, ...) plus an options property
|
|
@@ -98,33 +122,33 @@ the editor use, and the one <code>tsconfigDev</code> points at.</li>
|
|
|
98
122
|
<h2 id="usage" class="tsd-anchor-link">Usage<a href="#usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
|
|
99
123
|
<h3 id="projects" class="tsd-anchor-link">Projects<a href="#projects" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
|
|
100
124
|
<h4 id="aws-cdk-construct-library-project" class="tsd-anchor-link">AWS CDK Construct Library Project<a href="#aws-cdk-construct-library-project" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
|
|
101
|
-
<pre><code class="typescript"><span class="hl-
|
|
125
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">AwsCdkConstructLibraryProject</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">project</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">AwsCdkConstructLibraryProject</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-5">name:</span><span class="hl-1"> </span><span class="hl-2">"my-cdk-construct"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">repositoryUrl:</span><span class="hl-1"> </span><span class="hl-2">"https://github.com/nikovirtala/my-cdk-construct.git"</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">project</span><span class="hl-1">.</span><span class="hl-0">synth</span><span class="hl-1">();</span>
|
|
102
126
|
</code><button type="button">Copy</button></pre>
|
|
103
127
|
|
|
104
128
|
<h4 id="aws-cdk-typescript-app-project" class="tsd-anchor-link">AWS CDK TypeScript App Project<a href="#aws-cdk-typescript-app-project" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
|
|
105
|
-
<pre><code class="typescript"><span class="hl-
|
|
129
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">AwsCdkTypeScriptAppProject</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">project</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">AwsCdkTypeScriptAppProject</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-5">name:</span><span class="hl-1"> </span><span class="hl-2">"my-cdk-app"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">repository:</span><span class="hl-1"> </span><span class="hl-2">"https://github.com/nikovirtala/my-cdk-app.git"</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">project</span><span class="hl-1">.</span><span class="hl-0">synth</span><span class="hl-1">();</span>
|
|
106
130
|
</code><button type="button">Copy</button></pre>
|
|
107
131
|
|
|
108
132
|
<h4 id="jsii-project" class="tsd-anchor-link">JSII Project<a href="#jsii-project" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
|
|
109
|
-
<pre><code class="typescript"><span class="hl-
|
|
133
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">JsiiProject</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">project</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">JsiiProject</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-5">name:</span><span class="hl-1"> </span><span class="hl-2">"my-jsii-project"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">repositoryUrl:</span><span class="hl-1"> </span><span class="hl-2">"https://github.com/nikovirtala/my-jsii-project.git"</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">project</span><span class="hl-1">.</span><span class="hl-0">synth</span><span class="hl-1">();</span>
|
|
110
134
|
</code><button type="button">Copy</button></pre>
|
|
111
135
|
|
|
112
136
|
<h4 id="typescript-project" class="tsd-anchor-link">TypeScript Project<a href="#typescript-project" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
|
|
113
|
-
<pre><code class="typescript"><span class="hl-
|
|
137
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">TypeScriptProject</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">project</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">TypeScriptProject</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-5">name:</span><span class="hl-1"> </span><span class="hl-2">"my-typescript-project"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">repository:</span><span class="hl-1"> </span><span class="hl-2">"https://github.com/nikovirtala/my-typescript-project.git"</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">project</span><span class="hl-1">.</span><span class="hl-0">synth</span><span class="hl-1">();</span>
|
|
114
138
|
</code><button type="button">Copy</button></pre>
|
|
115
139
|
|
|
116
140
|
<h3 id="components" class="tsd-anchor-link">Components<a href="#components" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
|
|
117
141
|
<p>The package includes reusable components for common development tasks:</p>
|
|
118
142
|
<h4 id="vitest" class="tsd-anchor-link">Vitest<a href="#vitest" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
|
|
119
143
|
<p><a href="https://vitest.dev">Vitest</a> testing framework component.</p>
|
|
120
|
-
<pre><code class="typescript"><span class="hl-
|
|
144
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">Vitest</span><span class="hl-1">, </span><span class="hl-5">CoverageProvider</span><span class="hl-1">, </span><span class="hl-5">CoverageReporter</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">Vitest</span><span class="hl-1">(</span><span class="hl-5">project</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-5">vitestVersion:</span><span class="hl-1"> </span><span class="hl-2">"^5"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">config:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">coverageProvider:</span><span class="hl-1"> </span><span class="hl-5">CoverageProvider</span><span class="hl-1">.</span><span class="hl-6">V8</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">coverageReporters:</span><span class="hl-1"> [</span><span class="hl-5">CoverageReporter</span><span class="hl-1">.</span><span class="hl-6">TEXT</span><span class="hl-1">, </span><span class="hl-5">CoverageReporter</span><span class="hl-1">.</span><span class="hl-6">LCOV</span><span class="hl-1">],</span><br/><span class="hl-1"> },</span><br/><span class="hl-1">});</span>
|
|
121
145
|
</code><button type="button">Copy</button></pre>
|
|
122
146
|
|
|
123
147
|
<p>Type checking runs against the project's development tsconfig (<code>test/tsconfig.json</code>) unless
|
|
124
148
|
<code>config.typecheckTsconfig</code> says otherwise.</p>
|
|
125
149
|
<p>For Vitest settings that <code>config</code> doesn't cover, use <code>extraTestConfig</code> (merged into <code>test</code>) and
|
|
126
150
|
<code>extraConfig</code> (top-level options next to <code>test</code>):</p>
|
|
127
|
-
<pre><code class="typescript"><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">Vitest</span><span class="hl-1">(</span><span class="hl-5">project</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-5">extraTestConfig:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">setupFiles:</span><span class="hl-1"> [</span><span class="hl-2">"test/setup.ts"</span><span class="hl-1">],</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-5">extraConfig:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">resolve:</span><span class="hl-1"> { </span><span class="hl-5">alias:</span><span class="hl-1"> { </span><span class="hl-2">"@"</span><span class="hl-5">:</span><span class="hl-1"> </span><span class="hl-2">"/src"</span><span class="hl-1"> } },</span><br/><span class="hl-1"> },</span><br/><span class="hl-1">});</span>
|
|
151
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">Vitest</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">Vitest</span><span class="hl-1">(</span><span class="hl-5">project</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-5">extraTestConfig:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">setupFiles:</span><span class="hl-1"> [</span><span class="hl-2">"test/setup.ts"</span><span class="hl-1">],</span><br/><span class="hl-1"> },</span><br/><span class="hl-1"> </span><span class="hl-5">extraConfig:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">resolve:</span><span class="hl-1"> { </span><span class="hl-5">alias:</span><span class="hl-1"> { </span><span class="hl-2">"@"</span><span class="hl-5">:</span><span class="hl-1"> </span><span class="hl-2">"/src"</span><span class="hl-1"> } },</span><br/><span class="hl-1"> },</span><br/><span class="hl-1">});</span>
|
|
128
152
|
</code><button type="button">Copy</button></pre>
|
|
129
153
|
|
|
130
154
|
<p><code>extraTestConfig</code> is deep-merged over the generated <code>test</code> options: objects merge, and other values
|
|
@@ -132,18 +156,18 @@ the editor use, and the one <code>tsconfigDev</code> points at.</li>
|
|
|
132
156
|
can't contain functions or regular expressions, which rules out plugins.</p>
|
|
133
157
|
<h4 id="typedoc" class="tsd-anchor-link">TypeDoc<a href="#typedoc" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
|
|
134
158
|
<p><a href="https://typedoc.org">TypeDoc</a> documentation generation component.</p>
|
|
135
|
-
<pre><code class="typescript"><span class="hl-
|
|
159
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">TypeDoc</span><span class="hl-1">, </span><span class="hl-5">EntryPointStrategy</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">TypeDoc</span><span class="hl-1">(</span><span class="hl-5">project</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-5">version:</span><span class="hl-1"> </span><span class="hl-2">"^0.28"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">typeDocConfig:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">entryPointStrategy:</span><span class="hl-1"> </span><span class="hl-5">EntryPointStrategy</span><span class="hl-1">.</span><span class="hl-6">EXPAND</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">out:</span><span class="hl-1"> </span><span class="hl-2">"docs/api"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">exclude:</span><span class="hl-1"> [</span><span class="hl-2">"**/*.test.ts"</span><span class="hl-1">],</span><br/><span class="hl-1"> },</span><br/><span class="hl-1">});</span>
|
|
136
160
|
</code><button type="button">Copy</button></pre>
|
|
137
161
|
|
|
138
162
|
<h4 id="mise" class="tsd-anchor-link">Mise<a href="#mise" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
|
|
139
163
|
<p><a href="https://mise.jdx.dev">Mise</a> dev tools/runtimes management component.</p>
|
|
140
|
-
<pre><code class="typescript"><span class="hl-
|
|
164
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">Mise</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">Mise</span><span class="hl-1">(</span><span class="hl-5">project</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-5">nodeVersion:</span><span class="hl-1"> </span><span class="hl-2">"26.13.0"</span><span class="hl-1">,</span><br/><span class="hl-1">});</span>
|
|
141
165
|
</code><button type="button">Copy</button></pre>
|
|
142
166
|
|
|
143
167
|
<h4 id="homebrew" class="tsd-anchor-link">Homebrew<a href="#homebrew" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
|
|
144
168
|
<p><a href="https://brew.sh">Homebrew</a> package management component. Writes a <code>Brewfile</code> and adds an
|
|
145
169
|
<code>install:homebrew</code> task that bootstraps Homebrew and runs <code>brew bundle</code>.</p>
|
|
146
|
-
<pre><code class="typescript"><span class="hl-
|
|
170
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">Homebrew</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">homebrew</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">Homebrew</span><span class="hl-1">(</span><span class="hl-5">project</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-5">packages:</span><span class="hl-1"> [</span><span class="hl-2">"jq"</span><span class="hl-1">, </span><span class="hl-2">"yq"</span><span class="hl-1">],</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">homebrew</span><span class="hl-1">.</span><span class="hl-0">addPackage</span><span class="hl-1">(</span><span class="hl-2">"gh"</span><span class="hl-1">);</span>
|
|
147
171
|
</code><button type="button">Copy</button></pre>
|
|
148
172
|
|
|
149
173
|
<p>A fully qualified formula (<code>user/repository/formula</code>) also adds a <code>tap</code> entry. Since Homebrew 6,
|
|
@@ -151,27 +175,27 @@ formulae from non-official taps only load when trusted, so they're written with
|
|
|
151
175
|
That trusts only the formula, not the rest of its tap.</p>
|
|
152
176
|
<h4 id="colima" class="tsd-anchor-link">Colima<a href="#colima" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
|
|
153
177
|
<p><a href="https://github.com/abiosoft/colima">Colima</a> container runtime component. Alternative for Docker.</p>
|
|
154
|
-
<pre><code class="typescript"><span class="hl-
|
|
178
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">Colima</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">Colima</span><span class="hl-1">(</span><span class="hl-5">project</span><span class="hl-1">);</span>
|
|
155
179
|
</code><button type="button">Copy</button></pre>
|
|
156
180
|
|
|
157
181
|
<h4 id="localstack" class="tsd-anchor-link">LocalStack<a href="#localstack" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
|
|
158
182
|
<p><a href="https://www.localstack.cloud">LocalStack</a> AWS emulation component.</p>
|
|
159
|
-
<pre><code class="typescript"><span class="hl-
|
|
183
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">LocalStack</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">LocalStack</span><span class="hl-1">(</span><span class="hl-5">project</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-5">services:</span><span class="hl-1"> [</span><span class="hl-2">"s3"</span><span class="hl-1">, </span><span class="hl-2">"lambda"</span><span class="hl-1">, </span><span class="hl-2">"dynamodb"</span><span class="hl-1">],</span><br/><span class="hl-1"> </span><span class="hl-5">port:</span><span class="hl-1"> </span><span class="hl-7">4566</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">debug:</span><span class="hl-1"> </span><span class="hl-3">true</span><span class="hl-1">,</span><br/><span class="hl-1">});</span>
|
|
160
184
|
</code><button type="button">Copy</button></pre>
|
|
161
185
|
|
|
162
186
|
<h4 id="lambdafunctionconstructgenerator" class="tsd-anchor-link">LambdaFunctionConstructGenerator<a href="#lambdafunctionconstructgenerator" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
|
|
163
187
|
<p>Generates AWS CDK Lambda Function constructs and bundles their code.</p>
|
|
164
|
-
<pre><code class="typescript"><span class="hl-
|
|
188
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">LambdaFunctionConstructGenerator</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">LambdaFunctionConstructGenerator</span><span class="hl-1">(</span><span class="hl-5">project</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-5">sourceDir:</span><span class="hl-1"> </span><span class="hl-2">"src/handlers"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">outputDir:</span><span class="hl-1"> </span><span class="hl-2">"src/constructs/lambda"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">filePattern:</span><span class="hl-1"> </span><span class="hl-2">"*.lambda.ts"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">esbuildOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">minify:</span><span class="hl-1"> </span><span class="hl-3">true</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">sourcemap:</span><span class="hl-1"> </span><span class="hl-3">true</span><span class="hl-1">,</span><br/><span class="hl-1"> },</span><br/><span class="hl-1">});</span>
|
|
165
189
|
</code><button type="button">Copy</button></pre>
|
|
166
190
|
|
|
167
191
|
<h4 id="bundler" class="tsd-anchor-link">Bundler<a href="#bundler" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
|
|
168
192
|
<p>Low-level bundling utilities for Lambda functions.</p>
|
|
169
|
-
<pre><code class="typescript"><span class="hl-
|
|
193
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-5">Bundler</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">LambdaFunctionCodeBundle</span><span class="hl-1">,</span><br/><span class="hl-1">} </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">bundler</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">Bundler</span><span class="hl-1">(</span><span class="hl-5">project</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-5">assetsDir:</span><span class="hl-1"> </span><span class="hl-2">"assets"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">esbuildVersion:</span><span class="hl-1"> </span><span class="hl-2">"^0.25"</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">LambdaFunctionCodeBundle</span><span class="hl-1">(</span><span class="hl-5">project</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-5">entrypoint:</span><span class="hl-1"> </span><span class="hl-2">"src/my-function.lambda.ts"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">extension:</span><span class="hl-1"> </span><span class="hl-2">".lambda.ts"</span><span class="hl-1">,</span><br/><span class="hl-1">});</span>
|
|
170
194
|
</code><button type="button">Copy</button></pre>
|
|
171
195
|
|
|
172
196
|
<h4 id="projectgenerator" class="tsd-anchor-link">ProjectGenerator<a href="#projectgenerator" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4>
|
|
173
197
|
<p>Generates TypeScript project classes with standard configuration.</p>
|
|
174
|
-
<pre><code class="typescript"><span class="hl-
|
|
198
|
+
<pre><code class="typescript"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">ProjectGenerator</span><span class="hl-1">, </span><span class="hl-5">ProjectType</span><span class="hl-1">, </span><span class="hl-5">Mise</span><span class="hl-1">, </span><span class="hl-5">Vitest</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">ProjectGenerator</span><span class="hl-1">(</span><span class="hl-5">project</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-5">name:</span><span class="hl-1"> </span><span class="hl-2">"TypeScriptProject"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">projectType:</span><span class="hl-1"> </span><span class="hl-5">ProjectType</span><span class="hl-1">.</span><span class="hl-6">TYPE_SCRIPT_PROJECT</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">filePath:</span><span class="hl-1"> </span><span class="hl-2">"./src/projects/typescript.generated.ts"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-5">components:</span><span class="hl-1"> [</span><br/><span class="hl-1"> { </span><span class="hl-5">componentClass:</span><span class="hl-1"> </span><span class="hl-5">Mise</span><span class="hl-1"> },</span><br/><span class="hl-1"> { </span><span class="hl-5">componentClass:</span><span class="hl-1"> </span><span class="hl-5">Vitest</span><span class="hl-1"> }, </span><span class="hl-8">// Auto-detects VitestOptions from JSII manifest</span><br/><span class="hl-1"> ],</span><br/><span class="hl-1">});</span>
|
|
175
199
|
</code><button type="button">Copy</button></pre>
|
|
176
200
|
|
|
177
201
|
<p>Features:</p>
|
|
@@ -234,12 +258,12 @@ get new features or fixes. Every class, interface, enum and function they export
|
|
|
234
258
|
<li>
|
|
235
259
|
<p>In <code>.projenrc.ts</code>, replace the old package in <code>devDeps</code> with <code>@nikovirtala/projen-constructs</code>, and
|
|
236
260
|
change the imports:</p>
|
|
237
|
-
<pre><code class="typescript"><span class="hl-8">// before</span><br/><span class="hl-
|
|
261
|
+
<pre><code class="typescript"><span class="hl-8">// before</span><br/><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">Vitest</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-vitest"</span><span class="hl-1">;</span><br/><span class="hl-8">// after</span><br/><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">Vitest</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span>
|
|
238
262
|
</code><button type="button">Copy</button></pre>
|
|
239
263
|
|
|
240
264
|
</li>
|
|
241
265
|
<li>
|
|
242
|
-
<p>Check the peer dependencies. <code>@nikovirtala/projen-constructs</code> needs <code>projen</code> ^0.104, <code>constructs</code>
|
|
266
|
+
<p>Check the peer dependencies. <code>@nikovirtala/projen-constructs</code> needs <code>projen</code> ^0.104.23, <code>constructs</code>
|
|
243
267
|
^10 and <code>@mrgrain/cdk-esbuild</code> ^5. The standalone packages accepted older projen versions, so you
|
|
244
268
|
may have to upgrade projen in the same change.</p>
|
|
245
269
|
</li>
|
|
@@ -285,26 +309,44 @@ used to replace them all.</li>
|
|
|
285
309
|
</ul>
|
|
286
310
|
<p><strong>TypeDoc</strong>: no changes.</p>
|
|
287
311
|
<h3 id="from-to" class="tsd-anchor-link">From <code>AwsCdkApp</code> to <code>AwsCdkTypeScriptAppProject</code><a href="#from-to" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>
|
|
288
|
-
<pre><code class="typescript"><span class="hl-8">// before</span><br/><span class="hl-
|
|
312
|
+
<pre><code class="typescript"><span class="hl-8">// before</span><br/><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">AwsCdkApp</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-aws-cdk-app"</span><span class="hl-1">;</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">project</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">AwsCdkApp</span><span class="hl-1">({ </span><span class="hl-5">name:</span><span class="hl-1"> </span><span class="hl-2">"my-app"</span><span class="hl-1">, </span><span class="hl-5">cdkVersion:</span><span class="hl-1"> </span><span class="hl-2">"2.221.0"</span><span class="hl-1"> });</span><br/><br/><span class="hl-8">// after</span><br/><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">AwsCdkTypeScriptAppProject</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">"@nikovirtala/projen-constructs"</span><span class="hl-1">;</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">project</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-0">AwsCdkTypeScriptAppProject</span><span class="hl-1">({ </span><span class="hl-5">name:</span><span class="hl-1"> </span><span class="hl-2">"my-app"</span><span class="hl-1">, </span><span class="hl-5">cdkVersion:</span><span class="hl-1"> </span><span class="hl-2">"2.221.0"</span><span class="hl-1"> });</span>
|
|
289
313
|
</code><button type="button">Copy</button></pre>
|
|
290
314
|
|
|
291
|
-
<p>Both are ES module apps
|
|
315
|
+
<p>Both are ES module apps using pnpm, Biome, Vitest and mise. The differences:</p>
|
|
292
316
|
<ul>
|
|
293
|
-
<li
|
|
294
|
-
<
|
|
317
|
+
<li>
|
|
318
|
+
<p><strong>Native TypeScript</strong>: <code>.projenrc.ts</code> and the app run with <code>node</code> instead of <code>tsx</code>, and the
|
|
319
|
+
tsconfig sets <code>erasableSyntaxOnly</code> and <code>verbatimModuleSyntax</code> (see <a href="#native-typescript">Native TypeScript</a>).</p>
|
|
320
|
+
</li>
|
|
321
|
+
<li>
|
|
322
|
+
<p><strong><code>nvm</code> is removed.</strong> Use mise (on by default), which pins the Node.js version in <code>mise.toml</code>.</p>
|
|
323
|
+
</li>
|
|
324
|
+
<li>
|
|
325
|
+
<p><strong>Homebrew is on by default.</strong> The project gets a <code>Brewfile</code>, and <code>npx projen</code> runs
|
|
295
326
|
<code>install:homebrew</code> (installs Homebrew if <code>brew</code> is missing) and <code>homebrew:bundle</code>. Set
|
|
296
|
-
<code>homebrew: false</code> to turn it off.</
|
|
297
|
-
|
|
298
|
-
<li
|
|
327
|
+
<code>homebrew: false</code> to turn it off.</p>
|
|
328
|
+
</li>
|
|
329
|
+
<li>
|
|
330
|
+
<p><strong>cdk.json <code>app</code></strong> is <code>node src/main.ts</code> instead of <code>tsx --tsconfig tsconfig.json src/main.ts</code>.</p>
|
|
331
|
+
</li>
|
|
332
|
+
<li>
|
|
333
|
+
<p><strong>Defaults</strong> come from this library: Node.js, TypeScript, CDK and pnpm versions (pnpm 12 instead
|
|
299
334
|
of 10), Dependabot off, auto-merge on, <code>auto-approve</code> and <code>auto-merge</code> labels on dependency
|
|
300
335
|
upgrade PRs, and auto-approval of PRs by <code>nikovirtala</code>. Any option you set explicitly still wins,
|
|
301
|
-
so set <code>autoApproveOptions</code> if you aren't <code>nikovirtala</code>.</
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
<
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
<
|
|
336
|
+
so set <code>autoApproveOptions</code> if you aren't <code>nikovirtala</code>.</p>
|
|
337
|
+
</li>
|
|
338
|
+
<li>
|
|
339
|
+
<p><strong>tsconfig</strong>: <code>noImplicitOverride</code> and <code>allowSyntheticDefaultImports</code> move from <code>tsconfig.json</code>
|
|
340
|
+
to the development tsconfig (<code>test/tsconfig.json</code>).</p>
|
|
341
|
+
</li>
|
|
342
|
+
<li>
|
|
343
|
+
<p><strong>Options removed from the interface</strong>: <code>eslint</code>, <code>jest</code>, <code>prettier</code> (and their options),
|
|
344
|
+
<code>sampleCode</code> and <code>tsJestOptions</code>.</p>
|
|
345
|
+
</li>
|
|
346
|
+
<li>
|
|
347
|
+
<p><code>vitestOptions</code> takes the <code>VitestOptions</code> of this library, and now also <code>homebrewOptions</code> and
|
|
348
|
+
<code>miseOptions</code>.</p>
|
|
349
|
+
</li>
|
|
308
350
|
</ul>
|
|
309
351
|
<h2 id="development" class="tsd-anchor-link">Development<a href="#development" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>
|
|
310
352
|
<p>This project is managed by Projen and generates itself: <code>.projenrc.ts</code> defines the project using the
|
|
@@ -403,7 +445,8 @@ then synthesize again.</p>
|
|
|
403
445
|
<li>
|
|
404
446
|
<ul>
|
|
405
447
|
<li><a href="#pnpm"><span>pnpm</span></a></li>
|
|
406
|
-
<li><a href="#typescript-configuration"><span>Type<wbr/>Script configuration</span></a></li
|
|
448
|
+
<li><a href="#typescript-configuration"><span>Type<wbr/>Script configuration</span></a></li>
|
|
449
|
+
<li><a href="#native-typescript"><span>Native <wbr/>Type<wbr/>Script</span></a></li></ul></li>
|
|
407
450
|
<li><a href="#customization"><span>Customization</span></a></li>
|
|
408
451
|
<li><a href="#usage"><span>Usage</span></a></li>
|
|
409
452
|
<li>
|