feat(typings): create environment package to provide strict type chec…

…king for process.env (microsoft#20603)

* feat(typings): create environment package to provide strict type checking for process.env

* feat(tools): add new 'environment' global type to migration generator

* fixup! feat(typings): create environment package to provide strict type checking for process.env

* fixup! fixup! feat(typings): create environment package to provide strict type checking for process.env

* fixup! feat(tools): add new 'environment' global type to migration generator

* chore(typings): use solution config file to proerly check extensions/declaration without leaking globals

* feat(typings): make environment globals work everywhere with proper DX

tools/generators/migrate-converged-pkg/index.spec.ts

@@ -232,7 +232,7 @@ describe('migrate-converged-pkg generator', () => {
           lib: ['ES2019', 'dom'],
           noEmit: false,
           outDir: 'dist',
-          types: ['static-assets', 'inline-style-expand-shorthand'],
+          types: ['static-assets', 'environment', 'inline-style-expand-shorthand'],
         },
         exclude: ['./src/common/**', '**/*.spec.ts', '**/*.spec.tsx', '**/*.test.ts', '**/*.test.tsx'],
         include: ['./src/**/*.ts', './src/**/*.tsx'],
@@ -565,10 +565,9 @@ describe('migrate-converged-pkg generator', () => {
           allowJs: true,
           checkJs: true,
           outDir: '',
-          types: ['static-assets', 'inline-style-expand-shorthand', 'storybook__addons'],
+          types: ['static-assets', 'environment', 'inline-style-expand-shorthand', 'storybook__addons'],
         },
-        exclude: ['../src/common/**', '../**/*.spec.ts', '../**/*.spec.tsx', '../**/*.test.ts', '../**/*.test.tsx'],
-        include: ['../src/**/*', '*.js'],
+        include: ['../src/**/*.stories.ts', '../src/**/*.stories.tsx', '*.js'],
       });
       expect(readJson<TsConfig>(tree, paths.tsconfig.lib).exclude).toEqual(
         expect.arrayContaining(['**/*.stories.ts', '**/*.stories.tsx']),

tools/generators/migrate-converged-pkg/index.ts

@@ -163,7 +163,7 @@ const templates = {
             lib: ['ES2019'],
             outDir: 'dist',
             declaration: true,
-            types: ['static-assets'],
+            types: ['static-assets', 'environment'],
           } as TsConfig['compilerOptions'],
           exclude: ['**/*.spec.ts', '**/*.spec.tsx', '**/*.test.ts', '**/*.test.tsx'],
           include: ['./src/**/*.ts', './src/**/*.tsx'],
@@ -269,10 +269,7 @@ const templates = {
         allowJs: true,
         checkJs: true,
       },
-      exclude: [
-        /* added programmatically */
-      ],
-      include: ['../src/**/*', '*.js'],
+      include: ['../src/**/*.stories.ts', '../src/**/*.stories.tsx', '*.js'],
     },
   },
   e2e: {
@@ -576,12 +573,6 @@ function setupStorybook(tree: Tree, options: NormalizedSchema) {
       json.compilerOptions.types.push(...(libTsConfig.compilerOptions.types || []), 'storybook__addons');
       json.compilerOptions.types = uniqueArray(json.compilerOptions.types);
 
-      json.exclude = json.exclude || [];
-      const transformedExcludePaths = (libTsConfig.exclude || []).map(excludePath =>
-        transformRelativePath(excludePath),
-      );
-      json.exclude.push(...transformedExcludePaths);
-
       return json;
     });
 

typings/custom-global/index.d.ts

@@ -1,5 +1,6 @@
 // @TODO https://github.com/microsoft/fluentui/issues/20544
 /// <reference path="../static-assets/index.d.ts" />
+/// <reference path="../environment/index.d.ts" />
 
 /**
  * Generic typings for sass files.
@@ -63,21 +64,3 @@ declare interface SetConstructor {
 }
 /** Partial Set constructor representing what's available in IE 11 */
 declare var Set: SetConstructor;
-
-declare namespace NodeJS {
-  interface Process {
-    env: {
-      // This is mainly so we can do `process.env.NODE_ENV` checks without any extra conditionals.
-      //
-      // By default, webpack will (at compile time) replace instances of `process.env.NODE_ENV`
-      // with either "production" or "development" based on the `mode` property (webpack 4.0+).
-      // This is powered by the webpack DefinePlugin.
-      //
-      // For `mode` see: https://webpack.js.org/configuration/mode/#usage
-      // For DefinePlugin see: https://webpack.js.org/plugins/define-plugin/#root
-      [key: string]: string | undefined;
-    };
-  }
-}
-
-declare var process: NodeJS.Process;

typings/custom-global/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {},
+  "include": ["*.d.ts"]
+}

typings/environment/README.md

@@ -0,0 +1,49 @@
+# environment
+
+Enables access to `process.env` in both node and browser packages (your code needs to rely on wepback or bundler that understands node environment).
+
+This definition list of env variables is maintained manually and should be extended as needed.
+
+## Usage
+
+```json
+{
+  "compilerOptions": {
+    "types": ["environment"]
+  }
+}
+```
+
+Now you can use `process.env` global with strict type checking:
+
+```ts
+// @ExpectType string
+export function log(...messages: Array<string>) {
+  if (process.env.NODE_ENV === 'development') {
+    console.log(...messages);
+  }
+
+  // $ExpectError - 'prod' is not defined, did you mean to 'production' ?
+  if (process.env.NODE_ENV === 'prod') {
+    // do something
+  }
+}
+```
+
+## Adding env variables
+
+Add new env variables as needed
+
+**Example:**
+
+```diff
+// Adding NX_ENV env variable
+// ↓↓↓
+interface ExtendedProcessEnv {
+  NODE_ENV?: 'production' | 'development' | 'test';
+  LAGE_PACKAGE_NAME?: string;
+  CI?: string;
+  TF_BUILD?: string;
++ NX_ENV?: string
+}
+```

typings/environment/index.d.ts

@@ -0,0 +1,31 @@
+declare namespace NodeJS {
+  interface ExtendedProcessEnv {
+    // env: {
+    NODE_ENV?: 'production' | 'development' | 'test';
+    LAGE_PACKAGE_NAME?: string;
+    CI?: string;
+    TF_BUILD?: string;
+  }
+
+  /**
+   * extending/creating ProcessEnv interface which is used in @types/node to define `process.env`
+   *
+   * NOTE:
+   * To make it work with and without node globals it need to use same token name
+   * @see https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/node/v12/globals.d.ts#L764
+   */
+  export interface ProcessEnv extends ExtendedProcessEnv {}
+
+  /**
+   * extending/creating `Process` interface which is used in @types/node to define `process` global
+   *
+   * NOTE:
+   * To make it work with and without node globals it need to use same token name
+   * @see https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/node/v12/globals.d.ts#L883
+   */
+  export interface Process {
+    env: ProcessEnv;
+  }
+}
+
+declare var process: NodeJS.Process;

typings/environment/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {},
+  "include": ["*.d.ts"]
+}

typings/inline-style-expand-shorthand/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {},
+  "include": ["*.d.ts"]
+}

typings/package.json

@@ -3,6 +3,6 @@
   "version": "0.0.1",
   "private": true,
   "scripts": {
-    "type-check": "tsc -p ./tsconfig.json"
+    "type-check": "tsc -b ./tsconfig.json"
   }
 }

typings/static-assets/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {},
+  "include": ["*.d.ts"]
+}

typings/storybook__addons/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {},
+  "include": ["*.d.ts"]
+}

typings/tsconfig.json

@@ -5,8 +5,25 @@
     "allowSyntheticDefaultImports": true,
     "skipLibCheck": false,
     "noEmit": true,
-    "types": ["node"],
-    "typeRoots": ["node_modules/@types"]
+    "types": []
   },
-  "include": ["**/*.d.ts"]
+  "include": [],
+  "files": [],
+  "references": [
+    {
+      "path": "./environment/tsconfig.json"
+    },
+    {
+      "path": "./static-assets/tsconfig.json"
+    },
+    {
+      "path": "./inline-style-expand-shorthand/tsconfig.json"
+    },
+    {
+      "path": "./storybook__addons/tsconfig.json"
+    },
+    {
+      "path": "./custom-global/tsconfig.json"
+    }
+  ]
 }