[lit-html] Add isServer environment checker module (#3318)

Adds an `isServer` variable export to `lit` and `lit-html/is-server.js` which will be `true` in Node and `false` in the browser. This can be used when authoring components to change behavior based on whether or not the component is executing in an SSR context.

.changeset/eight-hairs-run.md

@@ -0,0 +1,6 @@
+---
+'lit': minor
+'lit-html': minor
+---
+
+Adds an `isServer` variable export to `lit` and `lit-html/is-server.js` which will be `true` in Node and `false` in the browser. This can be used when authoring components to change behavior based on whether or not the component is executing in an SSR context.

.eslintignore

@@ -75,6 +75,7 @@ packages/lit-html/async-directive.*
 packages/lit-html/polyfill-support.*
 packages/lit-html/private-ssr-support.*
 packages/lit-html/static.*
+packages/lit-html/is-server.*
 
 packages/lit-starter-js/node_modules/*
 packages/lit-starter-js/docs/*

.prettierignore

@@ -75,6 +75,7 @@ packages/lit-html/async-directive.*
 packages/lit-html/polyfill-support.*
 packages/lit-html/private-ssr-support.*
 packages/lit-html/static.*
+packages/lit-html/is-server.*
 
 packages/lit-starter-js/node_modules/
 packages/lit-starter-js/**/custom-elements.json

packages/lit-html/.gitignore

@@ -12,3 +12,4 @@
 /polyfill-support.*
 /private-ssr-support.*
 /static.*
+/is-server.*

packages/lit-html/package.json

@@ -180,6 +180,12 @@
       "node": "./node/static.js",
       "development": "./development/static.js",
       "default": "./static.js"
+    },
+    "./is-server.js": {
+      "types": "./development/is-server.d.ts",
+      "node": "./node/is-server.js",
+      "development": "./development/is-server.js",
+      "default": "./is-server.js"
     }
   },
   "scripts": {
@@ -205,6 +211,7 @@
     "/polyfill-support.{d.ts,d.ts.map,js,js.map}",
     "/private-ssr-support.{d.ts,d.ts.map,js,js.map}",
     "/static.{d.ts,d.ts.map,js,js.map}",
+    "/is-server.{d.ts,d.ts.map,js,js.map}",
     "/development/",
     "!/development/test/",
     "/directives/",
@@ -266,6 +273,7 @@
         "polyfill-support.js{,.map}",
         "private-ssr-support.js{,.map}",
         "static.js{,.map}",
+        "is-server.js{,.map}",
         "directives/*.js{,.map}",
         "test/*_test.html",
         "development/test/*_test.html",

packages/lit-html/rollup.config.js

@@ -39,6 +39,7 @@ export const defaultConfig = (options = {}) =>
       'experimental-hydrate',
       'private-ssr-support',
       'polyfill-support',
+      'is-server',
     ],
     bundled: [
       {

packages/lit-html/src/is-server.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+/**
+ * @fileoverview
+ *
+ * This file exports a boolean const whose value will depend on what environment
+ * the module is being imported from.
+ */
+
+const NODE_MODE = false;
+
+/**
+ * A boolean that will be `true` in server environments like Node, and `false`
+ * in browser environments. Note that your server environment or toolchain must
+ * support the `"node"` export condition for this to be `true`.
+ *
+ * This can be used when authoring components to change behavior based on
+ * whether or not the component is executing in an SSR context.
+ */
+export const isServer = NODE_MODE;

packages/lit-html/src/test/is-server_test.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+import {isServer} from 'lit-html/is-server.js';
+import {assert} from '@esm-bundle/chai';
+
+suite('is-server', () => {
+  test('isServer is false', () => {
+    assert.strictEqual(isServer, false);
+  });
+});

packages/lit-html/src/test/node-imports.ts

@@ -35,3 +35,7 @@ import 'lit-html/static.js';
 import 'lit-html/experimental-hydrate.js';
 import 'lit-html/private-ssr-support.js';
 import 'lit-html/polyfill-support.js';
+
+import assert from 'node:assert/strict';
+import {isServer} from 'lit-html/is-server.js';
+assert.strictEqual(isServer, true, 'Expected isServer to be true');

packages/lit/src/index.ts

@@ -11,3 +11,4 @@ import '@lit/reactive-element';
 import 'lit-html';
 
 export * from 'lit-element/lit-element.js';
+export * from 'lit-html/is-server.js';

packages/lit/src/test/node-imports.ts

@@ -45,3 +45,7 @@ import 'lit/html.js';
 import 'lit/experimental-hydrate-support.js';
 import 'lit/experimental-hydrate.js';
 import 'lit/static-html.js';
+
+import assert from 'node:assert/strict';
+import {isServer} from 'lit';
+assert.strictEqual(isServer, true, 'Expected isServer to be true');