@pwrdrvr/microapps-publish 0.2.5 → 0.2.9

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.
Files changed (2) hide show
  1. package/README.md +275 -73
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,117 +1,319 @@
1
1
  # Overview
2
2
 
3
- `microapps-publish` is used to deploy new apps and new versions for existing apps using the [MicroApps framework](https://github.com/pwrdrvr/microapps-core/).
3
+ `microapps-publish` is used to deploy new MicroApps and new versions for existing MicroApps using the [MicroApps framework](https://github.com/pwrdrvr/microapps-core/).
4
4
 
5
- # Getting Started
5
+ # Table of Contents <!-- omit in toc -->
6
6
 
7
- ## Next.js Apps
7
+ - [Overview](#overview)
8
+ - [Video Preview of Deploying an App](#video-preview-of-deploying-an-app)
9
+ - [Installation](#installation)
10
+ - [Usage](#usage)
11
+ - [Command - help](#command---help)
12
+ - [Command - preflight](#command---preflight)
13
+ - [Command - publish](#command---publish)
14
+ - [Command - publish-static](#command---publish-static)
15
+ - [Command - nextjs-version](#command---nextjs-version)
16
+ - [Command - nextjs-version-restore](#command---nextjs-version-restore)
17
+ - [Command - delete](#command---delete)
18
+ - [Command - nextjs-docker-auto](#command---nextjs-docker-auto)
8
19
 
9
- Create a Next.js app then follow the steps in this section to set it up for publishing to AWS Lambda @ Origin as a MicroApp. To publish new versions of the app use `npx microapps-publish --new-version x.y.z` when logged in to the target AWS account.
20
+ # Video Preview of Deploying an App
10
21
 
11
- ### Modify package.json
22
+ ![Video Preview of Deploying an App](https://raw.githubusercontent.com/pwrdrvr/microapps-core/main/assets/videos/microapps-publish-demo-deploy.gif)
12
23
 
13
- Replace the version with `0.0.0` so it can be modified by the `microapps-publish` tool.
24
+ # Installation
14
25
 
15
- ### Install Dependencies
26
+ `npm i -g @pwrdrvr/microapps-publish`
27
+
28
+ # Usage
29
+
30
+ ## Command - help
31
+
32
+ `npx microapps-publish help`
33
+
34
+ ```
35
+ Publish tool for deploying apps and updates
36
+
37
+ VERSION
38
+ @pwrdrvr/microapps-publish/0.0.0 darwin-x64 node-v16.13.1
39
+
40
+ USAGE
41
+ $ microapps-publish [COMMAND]
42
+
43
+ COMMANDS
44
+ delete Delete app/version
45
+ help display help for microapps-publish
46
+ nextjs-docker-auto Fully automatic publishing of Docker-based Lambda
47
+ function using Next.js and serverless-nextjs-router
48
+ nextjs-version Apply version to next.config.js overtop of 0.0.0
49
+ placeholder
50
+ nextjs-version-restore Restore next.config.js
51
+ preflight Check if app/version are available
52
+ publish Publish arbitrary framework app - deploy static
53
+ assets to S3, alias the $LATEST Lambda function, and
54
+ add integration/route to API Gateway.
55
+ publish-static Publish arbitrary framework static app - deploy
56
+ static assets to S3 only.
57
+ ```
58
+
59
+ ## Command - preflight
60
+
61
+ `npx microapps-publish preflight help`
16
62
 
17
63
  ```
18
- npm i --save-dev @sls-next/serverless-component@1.19.0 @pwrdrvr/serverless-nextjs-router @pwrdrvr/microapps-publish
64
+ Check if app/version are available
65
+
66
+ USAGE
67
+ $ microapps-publish preflight
68
+
69
+ OPTIONS
70
+ -a, --appName=appName Name of the MicroApp
71
+ -d, --deployerLambdaName=deployerLambdaName (required) Name of the deployer lambda function
72
+ -n, --newVersion=newVersion (required) New semantic version to apply
73
+
74
+ -o, --overwrite Allow overwrite - Warn but do not fail if version exists.
75
+ Discouraged outside of test envs if cacheable static files
76
+ have changed.
77
+
78
+ -v, --version show CLI version
79
+
80
+ --help show CLI help
81
+
82
+ EXAMPLE
83
+ $ microapps-publish preflight -d microapps-deployer-dev -a release -n 0.0.13
84
+ ✔ Preflight Version Check [0.2s]
85
+ ```
86
+
87
+ ## Command - publish
88
+
89
+ `npx microapps-publish publish help`
90
+
91
+ ```
92
+ Publish arbitrary framework app - deploy static assets to S3, alias the $LATEST Lambda function, and add integration/route to API Gateway.
93
+
94
+ USAGE
95
+ $ microapps-publish publish
96
+
97
+ OPTIONS
98
+ -a, --appName=appName MicroApps app name
99
+ -d, --deployerLambdaName=deployerLambdaName (required) Name of the deployer lambda function
100
+
101
+ -i, --defaultFile=defaultFile Default file to return when the app is loaded via the
102
+ router without a version (e.g. when app/ is requested).
103
+
104
+ -l, --appLambdaName=appLambdaName Name of the application lambda function
105
+
106
+ -n, --newVersion=newVersion (required) New semantic version to apply
107
+
108
+ -o, --overwrite Allow overwrite - Warn but do not fail if version exists.
109
+ Discouraged outside of test envs if cacheable static files
110
+ have changed.
111
+
112
+ -s, --staticAssetsPath=staticAssetsPath Path to files to be uploaded to S3 static bucket at
113
+ app/version/ path. Do include app/version/ in path if
114
+ files are already "rooted" under that path locally.
115
+
116
+ -v, --version show CLI version
117
+
118
+ --help show CLI help
119
+
120
+ --noCache Force revalidation of CloudFront and browser caching of
121
+ static assets
122
+
123
+ EXAMPLE
124
+ $ microapps-publish publish -d microapps-deployer-dev -l microapps-app-release-dev -a release -n 0.0.21
125
+ ✔ Get S3 Temp Credentials [1s]
126
+ ✔ Deploy to Lambda [0.6s]
127
+ ✔ Confirm Static Assets Folder Exists [0.0s]
128
+ ✔ Copy Static Files to Local Upload Dir [0.0s]
129
+ ✔ Enumerate Files to Upload to S3 [0.0s]
130
+ ✔ Upload Static Files to S3 [1s]
131
+ ✔ Creating MicroApp Application: release [0.0s]
132
+ ✔ Creating MicroApp Version: 0.0.21 [1s]
19
133
  ```
20
134
 
21
- ### Dockerfile
135
+ ## Command - publish-static
136
+
137
+ `npx microapps-publish publish-static help`
22
138
 
23
- Add this file to the root of the app.
139
+ ```
140
+ Publish arbitrary framework static app - deploy static assets to S3 only.
24
141
 
25
- ```Dockerfile
26
- FROM node:15-slim as base
142
+ USAGE
143
+ $ microapps-publish publish-static
27
144
 
28
- WORKDIR /app
145
+ OPTIONS
146
+ -a, --appName=appName MicroApps app name
147
+ -d, --deployerLambdaName=deployerLambdaName (required) Name of the deployer lambda function
29
148
 
30
- # Download the sharp libs once to save time
31
- # Do this before copying anything else in
32
- RUN mkdir -p image-lambda-npms && \
33
- cd image-lambda-npms && npm i sharp && \
34
- rm -rf node_modules/sharp/vendor/*/include/
149
+ -i, --defaultFile=defaultFile Default file to return when the app is loaded via the
150
+ router without a version (e.g. when app/ is requested).
35
151
 
36
- # Copy in the build output from `npx serverless`
37
- COPY .serverless_nextjs .
38
- COPY config.json .
152
+ -n, --newVersion=newVersion (required) New semantic version to apply
39
153
 
40
- # Move the sharp libs into place
41
- RUN rm -rf image-lambda/node_modules/ && \
42
- mv image-lambda-npms/node_modules image-labmda/ && \
43
- rm -rf image-lambda-npms
154
+ -o, --overwrite Allow overwrite - Warn but do not fail if version exists.
155
+ Discouraged outside of test envs if cacheable static files
156
+ have changed.
44
157
 
158
+ -s, --staticAssetsPath=staticAssetsPath Path to files to be uploaded to S3 static bucket at
159
+ app/version/ path. Do include app/version/ in path if
160
+ files are already "rooted" under that path locally.
45
161
 
162
+ -v, --version show CLI version
46
163
 
47
- FROM public.ecr.aws/lambda/nodejs:14 AS final
164
+ --help show CLI help
48
165
 
49
- # Copy in the munged code
50
- COPY --from=base /app .
166
+ --noCache Force revalidation of CloudFront and browser caching of
167
+ static assets
51
168
 
52
- CMD [ "./index.handler" ]
169
+ EXAMPLE
170
+ $ microapps-publish publish-static -d microapps-deployer-dev -l microapps-app-release-dev -a release -n
171
+ 0.0.21
172
+ ✔ Get S3 Temp Credentials [1s]
173
+ ✔ Confirm Static Assets Folder Exists [0.0s]
174
+ ✔ Copy Static Files to Local Upload Dir [0.0s]
175
+ ✔ Enumerate Files to Upload to S3 [0.0s]
176
+ ✔ Upload Static Files to S3 [1s]
177
+ ✔ Creating MicroApp Application: release [0.0s]
178
+ ✔ Creating MicroApp Version: 0.0.21 [1s]
53
179
  ```
54
180
 
55
- ### next.config.js
181
+ ## Command - nextjs-version
56
182
 
57
- Add this file to the root of the app.
183
+ `npx microapps-publish nextjs-version help`
58
184
 
59
- Replace `appname` with your URL path-compatible application name.
185
+ ```
186
+ Apply version to next.config.js overtop of 0.0.0 placeholder
187
+
188
+ USAGE
189
+ $ microapps-publish nextjs-version
60
190
 
61
- ```js
62
- const appRoot = '/appname/0.0.0';
191
+ OPTIONS
192
+ -l, --leaveCopy Leave a copy of the modifed files as .modified
193
+ -n, --newVersion=newVersion (required) New semantic version to apply
194
+ -v, --version show CLI version
195
+ --help show CLI help
63
196
 
64
- // eslint-disable-next-line no-undef
65
- module.exports = {
66
- target: 'serverless',
67
- webpack: (config, _options) => {
68
- return config;
69
- },
70
- basePath: appRoot,
71
- publicRuntimeConfig: {
72
- // Will be available on both server and client
73
- staticFolder: appRoot,
74
- },
75
- };
197
+ EXAMPLE
198
+ $ microapps-publish nextjs-version -n 0.0.13
199
+ ✔ Modifying Config Files [0.0s]
76
200
  ```
77
201
 
78
- ### deploy.json
202
+ ## Command - nextjs-version-restore
79
203
 
80
- Add this file to the root of the app.
204
+ `npx microapps-publish nextjs-version-restore help`
81
205
 
82
- Replace `appname` with your URL path-compatible application name.
206
+ ```
207
+ Apply version to next.config.js overtop of 0.0.0 placeholder
83
208
 
84
- ```json
85
- {
86
- "AppName": "appname",
87
- "SemVer": "0.0.0",
88
- "DefaultFile": "",
89
- "StaticAssetsPath": "./.serverless_nextjs/assets/appname/0.0.0/",
90
- "LambdaARN": "arn:aws:lambda:us-east-1:123456789012:function:appname:v0_0_0",
91
- "AWSAccountID": "123456789012",
92
- "AWSRegion": "us-east-2",
93
- "ServerlessNextRouterPath": "./node_modules/@pwrdrvr/serverless-nextjs-router/dist/index.js"
94
- }
209
+ USAGE
210
+ $ microapps-publish nextjs-version
211
+
212
+ OPTIONS
213
+ -l, --leaveCopy Leave a copy of the modifed files as .modified
214
+ -n, --newVersion=newVersion (required) New semantic version to apply
215
+ -v, --version show CLI version
216
+ --help show CLI help
217
+
218
+ EXAMPLE
219
+ $ microapps-publish nextjs-version -n 0.0.13
220
+ ✔ Modifying Config Files [0.0s]
95
221
  ```
96
222
 
97
- ### serverless.yaml
223
+ ## Command - delete
98
224
 
99
- Add this file to the root of the app.
225
+ `npx microapps-publish delete help`
100
226
 
101
- ```yaml
102
- nextApp:
103
- component: './node_modules/@sls-next/serverless-component'
104
- inputs:
105
- deploy: false
106
- uploadStaticAssetsFromBuild: false
107
227
  ```
228
+ Delete app/version
229
+
230
+ USAGE
231
+ $ microapps-publish delete
108
232
 
109
- # Current Limitations
233
+ OPTIONS
234
+ -a, --appName=appName Name of the MicroApp
110
235
 
111
- # Supports Only Docker-based Lambda Function
236
+ -d, --deployerLambdaName=deployerLambdaName (required) Name of the deployer
237
+ lambda function
112
238
 
113
- As of 2021-06-20, the tool invokes a Docker build to publish an app or an updated version of an existing app. This was convenient during initial development of the tool but can easily be de-coupled to allow the end user to publish their own Lambda version and simply pass the ARN as a reference to this publishing tool.
239
+ -n, --newVersion=newVersion (required) New semantic version
240
+ to apply
114
241
 
115
- # Supports Only for Next.js Apps
242
+ -v, --version show CLI version
243
+
244
+ --help show CLI help
245
+
246
+ EXAMPLE
247
+ $ microapps-publish delete -d microapps-deployer-dev -a release -n 0.0.13
248
+ ✔ App/Version deleted: release/0.0.13 [1.2s]
249
+ ```
116
250
 
117
- As of 2021-06-20, the tool is more tightly coupled with Next.js than it should be (i.e. it invokes a build using [serverless-next.js](https://github.com/serverless-nextjs/serverless-next.js) to build the Next.js app and it modifies versions in files needed to get Next.js apps to run in re-rooted directories). There is nothing that inherintly requires that apps use Next.js at all so this will be generalized to additional frameworks soon.
251
+ ## Command - nextjs-docker-auto
252
+
253
+ Note: semi-deprecated as of 2022-01-27. This command may still work but it performs too many tasks that needed to be split out into individual commands to allow for integration into various build processes.
254
+
255
+ `npx microapps-publish nextjs-docker-auto help`
256
+
257
+ ```
258
+ Fully automatic publishing of Docker-based Lambda function using Next.js and serverless-nextjs-router
259
+
260
+ USAGE
261
+ $ microapps-publish nextjs-docker-auto
262
+
263
+ OPTIONS
264
+ -a, --appName=appName
265
+ MicroApps app name
266
+
267
+ -d, --deployerLambdaName=deployerLambdaName
268
+ (required) Name of the deployer lambda function
269
+
270
+ -f, --leaveCopy
271
+ Leave a copy of the modifed files as .modified
272
+
273
+ -i, --defaultFile=defaultFile
274
+ Default file to return when the app is loaded via the router without a
275
+ version (e.g. when app/ is requested).
276
+
277
+ -l, --appLambdaName=appLambdaName
278
+ Name of the application lambda function
279
+
280
+ -n, --newVersion=newVersion
281
+ (required) New semantic version to apply
282
+
283
+ -o, --overwrite
284
+ Allow overwrite - Warn but do not fail if version exists. Discouraged
285
+ outside of test envs if cacheable static files have changed.
286
+
287
+ -r, --repoName=repoName
288
+ (required) Name (not URI) of the Docker repo for the app
289
+
290
+ -s, --staticAssetsPath=staticAssetsPath
291
+ Path to files to be uploaded to S3 static bucket at app/version/ path. Do
292
+ include app/version/ in path if files are already "rooted" under that path
293
+ locally.
294
+
295
+ -v, --version
296
+ show CLI version
297
+
298
+ --help
299
+ show CLI help
300
+
301
+ --noCache
302
+ Force revalidation of CloudFront and browser caching of static assets
303
+
304
+ EXAMPLE
305
+ $ microapps-publish nextjs-docker-auto -d microapps-deployer-dev -r
306
+ microapps-app-release-dev-repo -n 0.0.14
307
+ ✔ Logging into ECR [2s]
308
+ ✔ Modifying Config Files [0.0s]
309
+ ✔ Preflight Version Check [1s]
310
+ ✔ Serverless Next.js Build [1m16s]
311
+ ✔ Publish to ECR [32s]
312
+ ✔ Deploy to Lambda [11s]
313
+ ✔ Confirm Static Assets Folder Exists [0.0s]
314
+ ✔ Copy Static Files to Local Upload Dir [0.0s]
315
+ ✔ Enumerate Files to Upload to S3 [0.0s]
316
+ ✔ Upload Static Files to S3 [1s]
317
+ ✔ Creating MicroApp Application: release [0.2s]
318
+ ✔ Creating MicroApp Version: 0.0.14 [1s]
319
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pwrdrvr/microapps-publish",
3
- "version": "0.2.5",
3
+ "version": "0.2.9",
4
4
  "description": "Publish tool for deploying apps and updates",
5
5
  "main": "dist/index.js",
6
6
  "source": "src/index.ts",