From 9cb6efbb27c8dfc7991d762f3a583a477d4dc648 Mon Sep 17 00:00:00 2001 From: Raul Jimenez Ortega Date: Thu, 29 Jul 2021 11:37:33 +0200 Subject: [PATCH] Improving some readmes and simplifying ts-amd-cdn-nobundler-noframework --- docs/README.md | 88 +-------------- .../js-esm-local-vite-noframework/README.md | 7 +- .../README.md | 5 +- .../README.md | 101 +++++++++++++++++- .../package.json | 4 +- 5 files changed, 103 insertions(+), 102 deletions(-) diff --git a/docs/README.md b/docs/README.md index fbb5da7..815fdaa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,90 +8,4 @@ These docs aims to help you getting started with TypeScript to be able to use it 1. [How to run TypeScript](./1.how-to-run-js.md) 2. [Issues migrating from JavaScript to TypeScript](./2.issues-migrating-to-ts.md) -> **Warning**: currently, due to limitations in TypeScript, the [ArcGIS API for JavaScript autocasting](https://developers.arcgis.com/javascript/latest/programming-patterns/#autocasting) doesn't work when using TypeScript. - -# Configuration files - -This project includes two configuration files: `package.json` and `tsconfig.json`. - -## NPM's Package (package.json) - -In addition to metadata it includes: - -* All TypeScript definitions as developer dependencies: [`@types/arcgis-js-api`](https://www.npmjs.com/package/@types/arcgis-js-api), [`typescript`](https://www.npmjs.com/package/@types/arcgis-js-api), [`@types/chai`](https://www.npmjs.com/package/@types/chai) (optional?) and [`dojo-typings`](https://www.npmjs.com/package/dojo-typings) (optional?). - -* The definition of the script `npm run dev`: which runs the TypeScript compiler in watch mode (`tsc -w`). - -## TypeScript file (tsconfig.json) - -A first introduction to the [tsconfig.json](../tsconfig) can be [found here](https://developers.arcgis.com/javascript/latest/typescript-setup/#first-typescript-file). - -You could use this version: - -```js -{ - "compilerOptions": { - "module": "amd", - "sourceMap": true, - "target": "es2019", - "esModuleInterop": true - } -} -``` - -Or a more complex version: - -```js -{ - "compilerOptions": { - "module": "amd", - "noImplicitAny": true, - "esModuleInterop": true, - "sourceMap": true, - "target": "es2019", - "experimentalDecorators": true, - "preserveConstEnums": true, - "suppressImplicitAnyIndexErrors": true, - "moduleResolution": "node" - }, - "include": [ - "./app/*" - ], - "exclude": [ - "node_modules" - ] -} -``` - -There are three properties: - -* [`include`](https://www.typescriptlang.org/tsconfig#include): Specifies an array of filenames or patterns to include in the program. These filenames are resolved relative to the directory containing the tsconfig.json file. - -* [`exclude`](https://www.typescriptlang.org/tsconfig#exclude): Specifies an array of filenames or patterns that should be skipped when resolving include. - -* [`compilerOptions`](https://www.typescriptlang.org/tsconfig): which is an object with all the configuration that the TypeScript compiler (`tsc`) will use. - -Below we will explain each of the `compilerOptions` used in detail: - -* [`module`](https://www.typescriptlang.org/tsconfig#module): Sets the module system for the program. See the [Modules reference page](https://www.typescriptlang.org/docs/handbook/modules.html) for more information. Allowed values: -`CommonJS` (default if target is ES3 or ES5), `ES6`, `ES2015`, `ES2020`, `None`, `UMD`, `AMD`, `System` and `ESNext`. - -* [`noImplicitAny`](https://www.typescriptlang.org/tsconfig#noImplicitAny): In some cases where no type annotations are present, TypeScript will fall back to a type of any for a variable when it cannot infer the type. - -* [`esModuleInterop`](https://www.typescriptlang.org/tsconfig#module): When true, allows use of import syntax such as import x from 'xyz'. - -* [`sourceMap`](https://www.typescriptlang.org/tsconfig#module): Enables the generation of [sourcemap files](https://developer.mozilla.org/docs/Tools/Debugger/How_to/Use_a_source_map). These files allow debuggers and other tools to display the original TypeScript source code when actually working with the emitted JavaScript files. - -* [`target`](https://www.typescriptlang.org/tsconfig#target): Modern browsers support all ES6 features, so ES6 is a good choice. -Allowed:`ES3` (default), `ES5`, `ES6/ES2015`(synonymous), `ES7/ES2016`, `ES2017`, `ES2018`, `ES2019`, `ES2020`, `ESNext` - -* [`experimentalDecorators`](https://www.typescriptlang.org/tsconfig#experimentalDecorators): Enables [experimental support for decorators](https://github.com/tc39/proposal-decorators), which is in stage 2 of the TC39 standardization process. - -* [`preserveConstEnums`](https://www.typescriptlang.org/tsconfig#preserveConstEnums): Do not erase `const enum` declarations in generated code. `const enums` provide a way to reduce the overall memory footprint of your application at runtime by emitting the enum value instead of a reference. - -* [`suppressImplicitAnyIndexErrors`](https://www.typescriptlang.org/tsconfig#suppressImplicitAnyIndexErrors): Turning `suppressImplicitAnyIndexErrors `on suppresses reporting the error about implicit anys when indexing into objects, as shown in the following example: - -* [`moduleResolution`](https://www.typescriptlang.org/tsconfig#moduleResolution): Specify the module resolution strategy: `'node'` (Node.js) or `'classic'` (used in TypeScript before the release of 1.6). You probably won’t need to use `classic` in modern code. - - - +> **Warning**: currently, due to limitations in TypeScript, the [ArcGIS API for JavaScript autocasting](https://developers.arcgis.com/javascript/latest/programming-patterns/#autocasting) doesn't work when using TypeScript. \ No newline at end of file diff --git a/starter-apps/js-esm-local-vite-noframework/README.md b/starter-apps/js-esm-local-vite-noframework/README.md index 63d67ca..b487c3e 100644 --- a/starter-apps/js-esm-local-vite-noframework/README.md +++ b/starter-apps/js-esm-local-vite-noframework/README.md @@ -5,10 +5,9 @@ |JavaScript|None|Local|ESM|Vitejs| You can find a couple of videos about Vite.js + ArcGIS API JS API: - -- [Quick look at custom builds with ArcGIS JSAPI - min 16:54](https://youtu.be/VmzjaGfBRyo?t=1014) -- [Using Vite with ArcGIS JSAPI](https://www.youtube.com/watch?v=RF_q0tuMyic) -- [Web Developer Tooling - min 1:35](https://youtu.be/P_fLfP0O7lc?t=85) +* [Quick look at custom builds with ArcGIS JSAPI - min 16:54](https://youtu.be/VmzjaGfBRyo?t=1014) +* [Using Vite with ArcGIS JSAPI](https://www.youtube.com/watch?v=RF_q0tuMyic) +* [Web Developer Tooling - min 1:35](https://youtu.be/P_fLfP0O7lc?t=85) How lo load assets from the CDN instead of local: [ArcGIS API for JavaScript: Building Apps with ES Modules (hax) - min 34:21](https://youtu.be/ojrGonjJI2k?t=2061) diff --git a/starter-apps/js-esm-local-webpack-noframework/README.md b/starter-apps/js-esm-local-webpack-noframework/README.md index 7ebbb75..e4fa988 100644 --- a/starter-apps/js-esm-local-webpack-noframework/README.md +++ b/starter-apps/js-esm-local-webpack-noframework/README.md @@ -4,12 +4,11 @@ |---|---|---|---|---| |JavaScript|None|Local|ESM|Webpack| -You can find a couple of videos about Webpack + ArcGIS API JS API: - +You can find a couple of videos about [Webpack + ArcGIS API JS API at Esri Events Youtube Channel](https://www.youtube.com/c/EsriEvents/search?query=Webpack): * [ArcGIS API for JavaScript: Building Apps with ES Modules - min 11:02](https://youtu.be/ojrGonjJI2k?t=663) * [ArcGIS API for JavaScript: Building Apps with ES Modules (module federation) - 27:52](https://youtu.be/ojrGonjJI2k?t=1672) * [ArcGIS API for JavaScript: Options for Consuming the API - min 15:02](https://youtu.be/UL0m0EXW8Es?t=902) -* [Using ESM with ArcGIS API for JavaScript] +* [Using ESM with ArcGIS API for JavaScript](https://www.youtube.com/watch?v=C-8im8eEUPQ) How lo load assets from the CDN instead of local: [ArcGIS API for JavaScript: Building Apps with ES Modules (hax) - min 34:21](https://youtu.be/ojrGonjJI2k?t=2061) diff --git a/starter-apps/ts-amd-cdn-nobundler-noframework/README.md b/starter-apps/ts-amd-cdn-nobundler-noframework/README.md index 3160c78..9ade17d 100644 --- a/starter-apps/ts-amd-cdn-nobundler-noframework/README.md +++ b/starter-apps/ts-amd-cdn-nobundler-noframework/README.md @@ -8,12 +8,103 @@ To better understand the code of the `index.html`, `app/main.ts` and `tsconfig.json` files read this page [TypeScript - Setting up your development environment](https://developers.arcgis.com/javascript/latest/typescript-setup/). Or you watch a pretty similar demo inside [ArcGIS API for JavaScript: Using TypeScript - min 21:30](https://youtu.be/TYxHZb1HPqs?t=1290) -## Development +> Note: in the following video "[From Zero to Newbie with ArcGIS API for JS and TypeScript](https://www.youtube.com/watch?v=vkK22tmCeXQ)" (in spanish) there is an explanation on how to use this app. -* First time install the dependencies running: `npm run install`. -* Run the development environment: `npm run dev`. -* Open [index.html](index.html) - **recomendation**: use [Live Server extension](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer). -* Edit [app/main.ts](app/main.ts) and enjoy the IntelliSense & code snippets. +## Get Started + +**Step 1** - First time install the dependencies running: `npm run install`. + +**Step 2** - Run the development environment: `npm run dev`. + +**Step 3** - Open [index.html](./index.html) using a web server ([Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer), [http-server](https://www.npmjs.com/package/http-server), Apache, nginx, IIS, ...). + +**Step 4** - Make your edits to [`app/index.ts`](./app/index.ts) + +## Configuration files + +This project includes two configuration files: NPM's Package (`package.json`) and TypeScript file (`tsconfig.json`). + +### NPM's Package (package.json) + +In addition to metadata it includes: + +* All TypeScript definitions as developer dependencies: + + * [`@types/arcgis-js-api`](https://www.npmjs.com/package/@types/arcgis-js-api) + * [`typescript`](https://www.npmjs.com/package/@types/arcgis-js-api) + +* The definition of the script `npm run dev`: which runs the TypeScript compiler in watch mode (`tsc -w`). + +### TypeScript file (tsconfig.json) + +A first introduction to the [tsconfig.json](../tsconfig) can be [found here](https://developers.arcgis.com/javascript/latest/typescript-setup/#first-typescript-file). + +You could use this version: + +```js +{ + "compilerOptions": { + "module": "amd", + "sourceMap": true, + "target": "es2019", + "esModuleInterop": true + } +} +``` + +Or a more complex version: + +```js +{ + "compilerOptions": { + "module": "amd", + "noImplicitAny": true, + "esModuleInterop": true, + "sourceMap": true, + "target": "es2019", + "experimentalDecorators": true, + "preserveConstEnums": true, + "suppressImplicitAnyIndexErrors": true, + "moduleResolution": "node" + }, + "include": [ + "./app/*" + ], + "exclude": [ + "node_modules" + ] +} +``` + +There are three properties: + +* [`include`](https://www.typescriptlang.org/tsconfig#include): Specifies an array of filenames or patterns to include in the program. These filenames are resolved relative to the directory containing the tsconfig.json file. + +* [`exclude`](https://www.typescriptlang.org/tsconfig#exclude): Specifies an array of filenames or patterns that should be skipped when resolving include. + +* [`compilerOptions`](https://www.typescriptlang.org/tsconfig): which is an object with all the configuration that the TypeScript compiler (`tsc`) will use. + +Below we will explain each of the `compilerOptions` used in detail: + +* [`module`](https://www.typescriptlang.org/tsconfig#module): Sets the module system for the program. See the [Modules reference page](https://www.typescriptlang.org/docs/handbook/modules.html) for more information. Allowed values: +`CommonJS` (default if target is ES3 or ES5), `ES6`, `ES2015`, `ES2020`, `None`, `UMD`, `AMD`, `System` and `ESNext`. + +* [`noImplicitAny`](https://www.typescriptlang.org/tsconfig#noImplicitAny): In some cases where no type annotations are present, TypeScript will fall back to a type of any for a variable when it cannot infer the type. + +* [`esModuleInterop`](https://www.typescriptlang.org/tsconfig#module): When true, allows use of import syntax such as import x from 'xyz'. + +* [`sourceMap`](https://www.typescriptlang.org/tsconfig#module): Enables the generation of [sourcemap files](https://developer.mozilla.org/docs/Tools/Debugger/How_to/Use_a_source_map). These files allow debuggers and other tools to display the original TypeScript source code when actually working with the emitted JavaScript files. + +* [`target`](https://www.typescriptlang.org/tsconfig#target): Modern browsers support all ES6 features, so ES6 is a good choice. +Allowed:`ES3` (default), `ES5`, `ES6/ES2015`(synonymous), `ES7/ES2016`, `ES2017`, `ES2018`, `ES2019`, `ES2020`, `ESNext` + +* [`experimentalDecorators`](https://www.typescriptlang.org/tsconfig#experimentalDecorators): Enables [experimental support for decorators](https://github.com/tc39/proposal-decorators), which is in stage 2 of the TC39 standardization process. + +* [`preserveConstEnums`](https://www.typescriptlang.org/tsconfig#preserveConstEnums): Do not erase `const enum` declarations in generated code. `const enums` provide a way to reduce the overall memory footprint of your application at runtime by emitting the enum value instead of a reference. + +* [`suppressImplicitAnyIndexErrors`](https://www.typescriptlang.org/tsconfig#suppressImplicitAnyIndexErrors): Turning `suppressImplicitAnyIndexErrors `on suppresses reporting the error about implicit anys when indexing into objects, as shown in the following example: + +* [`moduleResolution`](https://www.typescriptlang.org/tsconfig#moduleResolution): Specify the module resolution strategy: `'node'` (Node.js) or `'classic'` (used in TypeScript before the release of 1.6). You probably won’t need to use `classic` in modern code. ## Acknowledgments diff --git a/starter-apps/ts-amd-cdn-nobundler-noframework/package.json b/starter-apps/ts-amd-cdn-nobundler-noframework/package.json index b3ab01a..0b232c0 100644 --- a/starter-apps/ts-amd-cdn-nobundler-noframework/package.json +++ b/starter-apps/ts-amd-cdn-nobundler-noframework/package.json @@ -27,8 +27,6 @@ "dependencies": {}, "devDependencies": { "typescript": "^3.4.3", - "@types/arcgis-js-api": "^4.20.0", - "@types/chai": "4.2.1", - "dojo-typings": "^1.11.9" + "@types/arcgis-js-api": "^4.20.0" } }