Allow dynamically loaded example files

Author: acelaya

Dockerfile

@@ -13,6 +13,7 @@ RUN rm -r /usr/share/nginx/html && rm /etc/nginx/conf.d/default.conf
 COPY --from=builder /frontend-shared/build /usr/share/nginx/html
 COPY ./templates/index.html /usr/share/nginx/html/index.html
 COPY ./images /usr/share/nginx/html/images
+COPY ./src/pattern-library/examples /usr/share/nginx/html/examples
 COPY conf/nginx.conf /etc/nginx/conf.d/default.conf
 
 EXPOSE 5001

README.md

@@ -49,3 +49,4 @@ import { Link } from '@hypothesis/frontend-shared';
 
 - [Development guide](docs/developing.md)
 - [Release guide](docs/releases.md)
+- [Adding examples](docs/examples.md)

docs/examples.md

@@ -0,0 +1,28 @@
+# Adding code examples
+
+Component library documentation frequently needs to show interactive examples, along with the code for them.
+
+Manually writing those code snippets has some issues: they are not covered by your type checking and linting tasks, and they can accidentally get outdated.
+
+The web-based documentation included with this library allows to create example files which are both used as regular modules that can be imported for interactive examples, but also read as plain text to generate their corresponding code snippet.
+
+These files are type-checked, formatted and linted like any other source files, and the code snippet will always be in sync with the interactive example.
+
+## Using example files
+
+When you want to create a code example, add a file with the name of your choice inside `src/pattern-library/examples` directory.
+
+You can then reference this file from the web-based pattern library, passing the `exampleFile` prop to the `<Library.Demo />` component.
+
+```tsx
+<Library.Demo exampleFile="some-example-file-name" />
+```
+
+## Considerations
+
+There are some considerations and limitations when working with example files.
+
+- They all need to have the `tsx` extension.
+- Nested directories are not supported, so it's a good idea to add contextual prefixes to example files. For example, all files related with `SelectNext` can be prefixed with `select-next` to make sure they are all grouped together.
+- Example files need to have a Preact component as their default export.
+- When generating the source code snippet, import statements are stripped out, to avoid internal module references which are not relevant for the library consumers.

package.json

@@ -14,6 +14,7 @@
     "@hypothesis/frontend-testing": "^1.2.2",
     "@rollup/plugin-babel": "^6.0.0",
     "@rollup/plugin-commonjs": "^25.0.0",
+    "@rollup/plugin-dynamic-import-vars": "^2.1.2",
     "@rollup/plugin-node-resolve": "^15.0.0",
     "@rollup/plugin-virtual": "^3.0.0",
     "@trivago/prettier-plugin-sort-imports": "^4.1.1",

rollup.config.js

@@ -1,5 +1,6 @@
 import { babel } from '@rollup/plugin-babel';
 import commonjs from '@rollup/plugin-commonjs';
+import dynamicImportVars from '@rollup/plugin-dynamic-import-vars';
 import { nodeResolve } from '@rollup/plugin-node-resolve';
 import { string } from 'rollup-plugin-string';
 
@@ -27,6 +28,7 @@ function bundleConfig(name, entryFile) {
         exclude: 'node_modules/**',
         extensions: ['.js', '.ts', '.tsx'],
       }),
+      dynamicImportVars(),
       nodeResolve({ extensions: ['.js', '.ts', '.tsx'] }),
       commonjs({ include: 'node_modules/**' }),
       string({

scripts/serve-pattern-library.js

@@ -11,6 +11,10 @@ export function servePatternLibrary(port = 4001) {
   app.use('/scripts', express.static(path.join(dirname, '../build/scripts')));
   app.use('/styles', express.static(path.join(dirname, '../build/styles')));
   app.use('/images', express.static(path.join(dirname, '../images')));
+  app.use(
+    '/examples',
+    express.static(path.join(dirname, '../src/pattern-library/examples')),
+  );
 
   // For any other path, serve the index.html file to allow client-side routing
   app.get('/:path?', (req, res) => {