feat: modernize examples (PROVCON-5981)

.github/workflows/test-and-release.yml

@@ -55,7 +55,7 @@ jobs:
     - uses: actions/checkout@v4.1.0
     - run: yarn --frozen-lockfile
     - run: yarn build.docs
-  e2e-react-cra:
+  e2e-react-vite:
     runs-on: ubuntu-latest
     container:
       image: cypress/base:22.21.0
@@ -64,8 +64,7 @@ jobs:
     needs:
     - build
     env:
-      example-name: react-cra
-      NODE_OPTIONS: --openssl-legacy-provider
+      example-name: react-vite
     steps:
     - uses: actions/download-artifact@v4.1.3
       with:
@@ -86,7 +85,7 @@ jobs:
     - uses: actions/upload-artifact@v4.1.0
       if: always()
       with:
-        name: e2e-react-cra-results
+        name: e2e-react-vite-results
         path: cypress/results
   e2e-angular:
     runs-on: ubuntu-latest
@@ -98,7 +97,6 @@ jobs:
     - build
     env:
       example-name: angular
-      NODE_OPTIONS: --openssl-legacy-provider
     steps:
     - uses: actions/download-artifact@v4.1.3
       with:
@@ -162,7 +160,7 @@ jobs:
     - lint-and-check
     - build
     - build-docs
-    - e2e-react-cra
+    - e2e-react-vite
     - e2e-static-html
     - e2e-angular
     steps:

.gitignore

@@ -39,8 +39,6 @@ dist-storybook
 *.log*
 *-debug.log*
 *-error.log*
-/examples/react-cra/yarn.lock
-/examples/angular/yarn.lock
 
 # Vim buffer files
 *.swp

CONTRIBUTING.md

@@ -148,11 +148,11 @@ yarn
 # Build Elements itself
 yarn build
 # Copy the contents of the predefined example application and make it use the local build
-yarn copy:react-cra
-# Build the chosen example (sub `react-cra` for any other example repo)
-yarn build:react-cra
+yarn copy:react-vite
+# Build the chosen example (sub `react-vite` for any other example repo)
+yarn build:react-vite
 # Run the example and the test suite against it
-yarn e2e:run:react-cra
+yarn e2e:run:react-vite
 ```
 > **Note**: You only need to run `yarn copy:$INTEGRATION-NAME` once after you clone the Elements repo.
 
@@ -168,11 +168,11 @@ yarn
 # Build Elements itself
 yarn build
 # Copy the contents of the predefined example application and make it use the local build
-yarn copy:react-cra
-# Build the chosen example (sub `react-cra` for any other example repo)
-yarn build:react-cra
+yarn copy:react-vite
+# Build the chosen example (sub `react-vite` for any other example repo)
+yarn build:react-vite
 # Run the example on port 4200. This is going to block so (unless you '&' it) or you'll need another terminal for the next step.
-yarn serve:react-cra
+yarn serve:react-vite
 # Open the Cypress console
 yarn e2e:open
 ```
@@ -181,7 +181,7 @@ yarn e2e:open
 
 With the console open, select any test suite to run it visually. Check [Cypress Docs](https://docs.cypress.io/guides/core-concepts/test-runner.html) for more details about the Test Runner.
 
-Don't forget that while *Cypress* hot-reloads on test code change, it needs a complete rebuild for *Elements* changes. There is no way around this for now. You won't hit this limitation often, but in case you do, one trick that may speed things up a bit is to substitute `yarn build:react-cra && yarn serve:react-cra` with `cd examples/react-cra; yarn start`.
+Don't forget that while *Cypress* hot-reloads on test code change, it needs a complete rebuild for *Elements* changes. There is no way around this for now. You won't hit this limitation often, but in case you do, one trick that may speed things up a bit is to substitute `yarn build:react-vite && yarn serve:react-vite` with `cd examples/react-vite; yarn start`.
 
 #### Edit the Tests
 

README.md

@@ -32,17 +32,18 @@ Let's chat about features, ideas, what you're doing with Elements, on [GitHub Di
 ## 👁️🗨 ️️Examples
 
 Stoplight Elements comes with a few example integration projects, showing you how to utilize Elements with different frameworks.
-- **[react-cra](./examples/react-cra)** - An example app built using Create React App utilizing Stoplight Elements.
-- **[angular](./examples/angular)** - An angular app utilizing the Web Components distribution of Elements.
-- **[bootstrap](./examples/bootstrap)** - A single HTML page utilizing the Web Components distribution via a global script tag.
+- **[react-vite](./examples/react-vite)** - A React app built with [Vite](https://vite.dev) utilizing Stoplight Elements.
+- **[angular](./examples/angular)** - An Angular app utilizing the Web Components distribution of Elements.
+- **[bootstrap](./examples/bootstrap)** - Single HTML pages (styled with Bootstrap) utilizing the Web Components distribution via a global script tag.
+- **[static-html](./examples/static-html)** - Plain HTML pages utilizing the Web Components distribution, served by a tiny Node.js server.
 
-To run these examples yourself:
+To run the **react-vite**, **angular** and **static-html** examples yourself:
 1. Clone this repo.
 2. Go to `examples` folder and open an example, e.g.: `examples/angular`.
 3. Run `yarn` to install all dependencies.
-4. Run `yarn start` to run the example.
+4. Run `yarn start` to run the example (for **static-html** run `yarn serve` instead).
 
-> **Note:** for **bootstrap** example just go straight to its directory and open the HTML file.
+> **Note:** for the **bootstrap** example just go straight to its directory and open the HTML files in a browser.
 
 ## 🏁 Usage
 

docs/getting-started/dev-portal/dev-portal-angular.md

@@ -49,7 +49,7 @@ Add the Elements CSS and JavaScript bundles to your Angular config.
 Generate a new Angular component for the API reference docs.
 
 ```bash
-yarn ng generate component api-reference
+yarn ng generate component api-reference --type=component
 ```
 
 This should generate an `api-reference` folder with a few files. In the `api-reference.component.html` file, add the Stoplight API component.
@@ -66,57 +66,39 @@ title: api-reference.component.html
 ></elements-stoplight-project>
 ```
 
-Notice `basePath` in the API component. You'll also want to add a route for the `/api-reference` path in the `app-routing.module.ts` file. It's important to add a catch-all route `**` so you can deep link to paths in API reference docs.
+Notice `basePath` in the component above. You'll also want to add a route for the `/api-reference` path in the `app.routes.ts` file. It's important to add a catch-all route (`**`) so you can deep link to paths in the API reference docs.
 
-Your routing file should end up looking like this:
+Your routes file should end up looking like this:
 
 <!--
-title: app-routing.module.ts
+title: app.routes.ts
 -->
 ```ts
-import { NgModule } from '@angular/core';
-import { Routes, RouterModule } from '@angular/router';
+import { Routes } from '@angular/router';
+
 import { ApiReferenceComponent } from './api-reference/api-reference.component';
-import { AppComponent } from './app.component';
-
-const routes: Routes = [
-  { path: '', component: AppComponent, pathMatch: 'full' },
-  {
-    path: 'api-reference',
-    component: ApiReferenceComponent,
-    children: [{ path: '**', component: ApiReferenceComponent }],
-  },
-];
 
-@NgModule({
-  imports: [RouterModule.forRoot(routes)],
-  exports: [RouterModule],
-})
-export class AppRoutingModule {}
+export const routes: Routes = [
+  { path: 'api-reference/**', component: ApiReferenceComponent },
+];
 ```
-And finally, set up Angular to allow [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components). Head over to the `app-module.ts` file and add the [CUSTOM_ELEMENTS_SCHEMA](https://angular.io/api/core/CUSTOM_ELEMENTS_SCHEMA).
+
+Finally, set up Angular to allow [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components). Head over to the `api-reference.component.ts` file and add the [CUSTOM_ELEMENTS_SCHEMA](https://angular.dev/api/core/CUSTOM_ELEMENTS_SCHEMA) to the component.
 
 It'll end up looking like this:
 
 <!--
-title: app-module.ts
+title: api-reference.component.ts
 -->
 ```ts
-import { BrowserModule } from '@angular/platform-browser';
-import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-
-import { AppRoutingModule } from './app-routing.module';
-import { AppComponent } from './app.component';
-import { ApiReferenceComponent } from './api-reference/api-reference.component';
+import { CUSTOM_ELEMENTS_SCHEMA, Component } from '@angular/core';
 
-@NgModule({
+@Component({
+  selector: 'app-api-reference',
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  declarations: [AppComponent, ApiReferenceComponent],
-  imports: [BrowserModule, AppRoutingModule],
-  providers: [],
-  bootstrap: [AppComponent],
+  templateUrl: './api-reference.component.html',
 })
-export class AppModule {}
+export class ApiReferenceComponent {}
 ```
 
 ## Fire it up

docs/getting-started/dev-portal/react.md

@@ -7,7 +7,7 @@ Learn how to get started with Elements Dev Portal in a React project.
 Use the [React App template](https://github.com/stoplightio/cra-template-elements-dev-portal) to create a new Elements Dev Portal website in React without additional setup.
 
 > Note: [The Create React App template only works with version 4 of create-react-app because of Webpack 5 polyfill issues.](https://github.com/facebook/create-react-app/issues/11756)
-> To run it with new create-react-app and Webpack 5 check [Polyfills](#Polyfills) section
+> To run it with new create-react-app and Webpack 5 check [Polyfills](#polyfills-create-react-app) section
 
 ```bash
 npx create-react-app my-dir --template @stoplight/elements-dev-portal
@@ -81,7 +81,22 @@ yarn start
 
 And you should see the API reference documentation for the Zoom API.
 
-## Polyfills
+## Vite
+
+Elements dependencies expect some Node.js globals and built-ins (`global`, `process`, `url`, `buffer`), which Vite doesn't provide. Add [vite-plugin-node-polyfills](https://github.com/davidmyersdev/vite-plugin-node-polyfills) to your Vite config. See the [react-vite example](https://github.com/stoplightio/elements/tree/main/examples/react-vite) for a complete setup.
+
+```js
+// vite.config.ts
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+import { nodePolyfills } from 'vite-plugin-node-polyfills';
+
+export default defineConfig({
+  plugins: [react(), nodePolyfills()],
+});
+```
+
+## Polyfills (Create React App)
 Create React App is now using Webpack 5 that doesn't come with node polyfills anymore. Since elements dependencies use `url` and `buffer` packages they need to be added separately. The easiest way to do that is to include [node-polyfill-webpack-plugin](https://github.com/Richienb/node-polyfill-webpack-plugin) in webpack configuration file:
 ```js
 const NodePolyfillPlugin = require('node-polyfill-webpack-plugin');

docs/getting-started/elements/angular.md

@@ -42,7 +42,7 @@ Add the Elements CSS and JavaScript bundles to your Angular config.
 Now, generate a new Angular component for your API reference docs.
 
 ```bash
-yarn ng generate component api-reference
+yarn ng generate component api-reference --type=component
 ```
 
 This should generate an `api-reference` folder with a few files. In the `api-reference.component.html` file, add the Stoplight API component.
@@ -57,58 +57,39 @@ title: api-reference.component.html
 ></elements-api>
 ```
 
-Notice `basePath` in the API component. Add a route for the `/api-reference` path in the `app-routing.module.ts` file. It's important to add a catch-all route `**` so you can deep link to paths in the API reference docs.
+Notice `basePath` in the component above. Add a route for the `/api-reference` path in the `app.routes.ts` file. It's important to add a catch-all route (`**`) so you can deep link to paths in the API reference docs.
 
-Your routing file should end up looking like this:
+Your routes file should end up looking like this:
 
 <!--
-title: app-routing.module.ts
+title: app.routes.ts
 -->
 ```ts
-import { NgModule } from '@angular/core';
-import { Routes, RouterModule } from '@angular/router';
+import { Routes } from '@angular/router';
+
 import { ApiReferenceComponent } from './api-reference/api-reference.component';
-import { AppComponent } from './app.component';
-
-const routes: Routes = [
-  { path: '', component: AppComponent, pathMatch: 'full' },
-  {
-    path: 'api-reference',
-    component: ApiReferenceComponent,
-    children: [{ path: '**', component: ApiReferenceComponent }],
-  },
-];
 
-@NgModule({
-  imports: [RouterModule.forRoot(routes)],
-  exports: [RouterModule],
-})
-export class AppRoutingModule {}
+export const routes: Routes = [
+  { path: 'api-reference/**', component: ApiReferenceComponent },
+];
 ```
 
-Finally, set up Angular to allow [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components). Head over to the `app-module.ts` file and add the [CUSTOM_ELEMENTS_SCHEMA](https://angular.io/api/core/CUSTOM_ELEMENTS_SCHEMA).
+Finally, set up Angular to allow [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components). Head over to the `api-reference.component.ts` file and add the [CUSTOM_ELEMENTS_SCHEMA](https://angular.dev/api/core/CUSTOM_ELEMENTS_SCHEMA) to the component.
 
 It'll end up looking like this:
 
 <!--
-title: app-module.ts
+title: api-reference.component.ts
 -->
 ```ts
-import { BrowserModule } from '@angular/platform-browser';
-import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-
-import { AppRoutingModule } from './app-routing.module';
-import { AppComponent } from './app.component';
-import { ApiReferenceComponent } from './api-reference/api-reference.component';
+import { CUSTOM_ELEMENTS_SCHEMA, Component } from '@angular/core';
 
-@NgModule({
+@Component({
+  selector: 'app-api-reference',
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  declarations: [AppComponent, ApiReferenceComponent],
-  imports: [BrowserModule, AppRoutingModule],
-  providers: [],
-  bootstrap: [AppComponent],
+  templateUrl: './api-reference.component.html',
 })
-export class AppModule {}
+export class ApiReferenceComponent {}
 ```
 
 ## Fire it up

docs/getting-started/elements/react.md

@@ -7,7 +7,7 @@ Learn how to get started with Elements in a React project.
 Use the [React App template](https://github.com/stoplightio/cra-template-elements) to create a new Elements website in React without any additional setup.
 
 > Note: [The Create React App template only works with version 4 of create-react-app because of Webpack 5 polyfill issues.](https://github.com/facebook/create-react-app/issues/11756)
-> To run it with new create-react-app and Webpack 5 check [Polyfills](#Polyfills) section
+> To run it with new create-react-app and Webpack 5 check [Polyfills](#polyfills-create-react-app) section
 
 ```bash
 npx create-react-app@4.0.3 my-dir --template @stoplight/elements
@@ -110,7 +110,22 @@ const apiDescriptionDocument = {
 />
 ```
 
-## Polyfills
+## Vite
+
+Elements dependencies expect some Node.js globals and built-ins (`global`, `process`, `url`, `buffer`), which Vite doesn't provide. Add [vite-plugin-node-polyfills](https://github.com/davidmyersdev/vite-plugin-node-polyfills) to your Vite config. See the [react-vite example](https://github.com/stoplightio/elements/tree/main/examples/react-vite) for a complete setup.
+
+```js
+// vite.config.ts
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+import { nodePolyfills } from 'vite-plugin-node-polyfills';
+
+export default defineConfig({
+  plugins: [react(), nodePolyfills()],
+});
+```
+
+## Polyfills (Create React App)
 Create React App is now using Webpack 5 that doesn't come with node polyfills anymore. Since elements dependencies use `url` and `buffer` packages they need to be added separately. The easiest way to do that is to include [node-polyfill-webpack-plugin](https://github.com/Richienb/node-polyfill-webpack-plugin) in webpack configuration file:
 ```js
 const NodePolyfillPlugin = require('node-polyfill-webpack-plugin');

examples/angular/.gitignore

@@ -1,37 +1,3 @@
-# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
-
-# dependencies
-node_modules
-/.pnp
-.pnp.js
-
-# testing
-/coverage
-packages/*/coverage
-cypress/results
-
-# production
-build
-dist
-docs-auto
-
-# misc
-.DS_Store
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
-.vscode
-.idea
-.nyc_output
-.DS_Store
-.awcache
-.cache-loader
-.cache
-.rpt2_cache
-.eslintcache
-
-# logs
-*.log*
-*-debug.log*
-*-error.log*
+/node_modules
+/dist
+/.angular