Implement custom entry

.changeset/strong-suits-end.md

@@ -0,0 +1,12 @@
+---
+'playroom': minor
+---
+
+Add custom entry file support
+
+You can provide a custom entry file via the `entry` option, which is a path to a file that runs some code before everything else. For example, if you wanted to apply a CSS reset or other global styles, polyfills etc.:
+
+```js
+import '../path/to/your/theming-system/reset';
+import '../path/to/your/theming-system/global-styles.css';
+```

README.md

@@ -62,6 +62,7 @@ module.exports = {
 
   // Optional:
   title: 'My Awesome Library',
+  entry: './src/entry',
   themes: './src/themes',
   snippets: './playroom/snippets.js',
   frameComponent: './playroom/FrameComponent.js',
@@ -158,6 +159,15 @@ export default function useScope() {
   };
 ```
 
+## Custom Entry
+
+You can provide a custom entry file via the `entry` option, which is a path to a file that runs some code before everything else. For example, if you wanted to apply a CSS reset or other global styles, polyfills etc.:
+
+```js
+import '../path/to/your/theming-system/reset';
+import '../path/to/your/theming-system/global-styles.css';
+```
+
 ## Theme Support
 
 If your component library has multiple themes, you can customise Playroom to render every theme simultaneously via the `themes` configuration option.

cypress/e2e/entry.cy.js

@@ -0,0 +1,71 @@
+import {
+  assertPreviewContains,
+  cleanUp,
+  getFirstFrame,
+  typeCode,
+  visit,
+} from '../support/utils';
+
+const assertGlobalCounter = () => cy.window().its('counter').should('equal', 1);
+const assertGlobalCounterInIframe = ($iframe) =>
+  cy.wrap($iframe[0].contentWindow).its('counter').should('equal', 1);
+
+describe('Entry', () => {
+  afterEach(() => {
+    cleanUp();
+  });
+
+  describe('single entry', () => {
+    describe('loads the entry only once', () => {
+      it('for main app', () => {
+        cy.visit('http://localhost:9002');
+        // introduce some delay to make sure everything loads
+        typeCode('-');
+
+        assertGlobalCounter();
+      });
+
+      it('for frames', () => {
+        visit('http://localhost:9002');
+        // introduce some delay to make sure everything loads
+        typeCode('-');
+
+        getFirstFrame().then(($frame) => {
+          assertGlobalCounterInIframe($frame);
+        });
+      });
+
+      it('for preview', () => {
+        cy.visit(
+          'http://localhost:9002/preview#code=N4Igxg9gJgpiBcIC0IC%2BQ'
+        ).then(() => {
+          cy.get('[data-testid="splashscreen"]').should('not.be.visible');
+        });
+        // wait for rendering to finish to make sure everything loads
+        assertPreviewContains('-');
+
+        assertGlobalCounter();
+      });
+    });
+  });
+
+  describe('multiple entries', () => {
+    it('loads the entry for frames', () => {
+      visit('http://localhost:9001/index.html');
+      // introduce some delay to make sure everything loads
+      typeCode('-');
+
+      getFirstFrame().then(($frame) => {
+        assertGlobalCounterInIframe($frame);
+      });
+    });
+
+    it('does not load the entry for main app', () => {
+      visit('http://localhost:9001/index.html');
+      // introduce some delay to make sure everything loads
+      typeCode('-');
+
+      cy.window().its('counter').should('not.exist');
+    });
+  });
+});

cypress/projects/themed/entry.js

@@ -0,0 +1 @@
+window.counter = 1;

cypress/projects/themed/playroom.config.js

@@ -1,4 +1,7 @@
 module.exports = {
+  entry: {
+    frame: './entry',
+  },
   components: './components',
   snippets: './snippets',
   themes: './themes',

cypress/projects/typescript/entry.mjs

@@ -0,0 +1,5 @@
+import { counter, increment } from './state.mjs';
+
+export default counter;
+
+increment();

cypress/projects/typescript/playroom.config.js

@@ -1,4 +1,5 @@
 module.exports = {
+  entry: './entry.mjs',
   components: './components.ts',
   snippets: './snippets.ts',
   outputPath: './dist',

cypress/projects/typescript/state.mjs

@@ -0,0 +1,9 @@
+/* eslint-disable no-console */
+
+export let counter = 0;
+
+export function increment() {
+  window.counter = ++counter;
+
+  console.log('incremented', window.counter);
+}

cypress/support/utils.js

@@ -1,5 +1,8 @@
 // eslint-disable-next-line spaced-comment
 /// <reference types="cypress" />
+// eslint-disable-next-line spaced-comment
+/// <reference types="cypress-iframe" />
+import 'cypress-iframe';
 import dedent from 'dedent';
 
 import { createUrl } from '../../utils';
@@ -9,22 +12,16 @@ const WAIT_FOR_FRAME_TO_RENDER = 1000;
 
 const getCodeEditor = () => cy.get('.CodeMirror-code');
 
-export const getPreviewFrames = () => cy.get('[data-testid="previewFrame"]');
-
-export const getPreviewFrameNames = () => cy.get('[data-testid="frameName"]');
+const getPreviewFrameNames = () => cy.get('[data-testid="frameName"]');
 
-export const getFirstFrame = () => getPreviewFrames().first();
+export const getFirstFrame = () =>
+  cy.frameLoaded('[data-testid="previewFrame"]:first');
 
 export const visit = (url) =>
   cy
     .visit(url)
     .reload()
-    .then(() => {
-      getFirstFrame().then(
-        ($iframe) =>
-          new Cypress.Promise((resolve) => $iframe.on('load', resolve))
-      );
-    });
+    .then(() => getFirstFrame());
 
 export const typeCode = (code, { delay = 200 } = {}) =>
   getCodeEditor()
@@ -153,24 +150,23 @@ export const assertPreviewContains = (text) =>
       expect(el.get(0).innerText).to.eq(text);
     });
 
+export const cleanUp = () =>
+  cy
+    .window()
+    .then((win) => {
+      const { storageKey } = win.__playroomConfig__;
+      indexedDB.deleteDatabase(storageKey);
+    })
+    .reload();
+
 export const loadPlayroom = (initialCode) => {
   const baseUrl = 'http://localhost:9000';
   const visitUrl = initialCode
     ? createUrl({ baseUrl, code: dedent(initialCode) })
     : baseUrl;
 
-  return cy
-    .visit(visitUrl)
-    .window()
-    .then((win) => {
-      const { storageKey } = win.__playroomConfig__;
-      indexedDB.deleteDatabase(storageKey);
-    })
-    .reload()
-    .then(() =>
-      getFirstFrame().then(
-        ($iframe) =>
-          new Cypress.Promise((resolve) => $iframe.on('load', resolve))
-      )
-    );
+  cy.visit(visitUrl);
+  cleanUp();
+
+  return getFirstFrame();
 };

lib/defaultModules/entry.js

@@ -0,0 +1 @@
+// this doesn't do anything by default

lib/makeWebpackConfig.js

@@ -37,12 +37,27 @@ module.exports = async (playroomConfig, options) => {
 
   const staticTypes = await getStaticTypes(playroomConfig);
 
+  const customEntries = Object.fromEntries(
+    ['index', 'frame', 'preview'].map((entryName) => {
+      const customEntry =
+        typeof playroomConfig.entry === 'object'
+          ? playroomConfig.entry[entryName]
+          : playroomConfig.entry;
+      return [
+        entryName,
+        customEntry
+          ? relativeResolve(customEntry)
+          : require.resolve('./defaultModules/entry'),
+      ];
+    })
+  );
+
   const ourConfig = {
     mode: options.production ? 'production' : 'development',
     entry: {
-      index: [require.resolve('../src/index.js')],
-      frame: [require.resolve('../src/frame.js')],
-      preview: [require.resolve('../src/preview.js')],
+      index: [customEntries.index, require.resolve('../src/index.js')],
+      frame: [customEntries.frame, require.resolve('../src/frame.js')],
+      preview: [customEntries.preview, require.resolve('../src/preview.js')],
     },
     output: {
       filename: '[name].[contenthash].js',

package.json

@@ -119,6 +119,7 @@
     "@types/react-helmet": "^6.1.6",
     "concurrently": "^7.6.0",
     "cypress": "^12.0.2",
+    "cypress-iframe": "^1.0.1",
     "eslint": "^8.44.0",
     "eslint-config-seek": "^11.3.1",
     "husky": "^8.0.2",

src/index.d.ts

@@ -2,6 +2,13 @@ interface PlayroomConfig {
   components: string;
   outputPath: string;
   title?: string;
+  entry?:
+    | string
+    | {
+        index?: string;
+        frame?: string;
+        preview?: string;
+      };
   themes?: string;
   widths?: number[];
   snippets?: Snippet[];