drbobbeaty/zoid-demo

A clonable demo project for xcomponent

zoid demo

A forkable demo repo for zoid to help you get started.

zoid is a cross-domain component library which helps you render iframes and popups, pass down props, accept callbacks, and much more. This repo sets you up with the best possible starting point for building an xcomponent, including:

• Predefined webpack, babel, karma etc. configs for working with xcomponent
• Predefined test-setup, including a mock component frame
• Predefined demo pages for both iframe and popup components

Useful starting points

• Component definition
• Component implementation - iframe mode - this will need to be exposed on the service so that it can be loaded by the users. This is covered in Deploying, below.
• Component implementation - popup mode - this will need to be exposed on the service so that it can be loaded by the users. This is covered in Deploying, below.
• Demo in iframe mode
• Demo in popup mode
• Component test

Quick Start

Getting Started

• Install npm from Homebrew: brew install npm
• Fork the module
• Install the serve component: npm install -D serve
• Install everything else: npm install
• Start editing code in ./src and writing tests in ./tests
• Update the package.json file with values for the new project:
  • Update the name, version, description values
  • Update the repository.url value for the new repo
• Update the webpack.config.js file with the values for the project:
  • Update the FILE_NAME for generated file name.
  • Update the MODULE_NAME for the module to place this zoid
• Build: npm run build

Building

npm run build

Running Demo Server

npm run demo

Deploying

• Host your bundled xcomponent script somewhere, e.g. https://mysite.com/login-zoid-component.frame.js or https://mysite.com/login-zoid-component.popup.js
• Set up a public url for your component, e.g. https://mysite.com/login
• Make sure the login-zoid-component.frame.js is included in the login page, and using window.xprops to obtain the data from the user.

Now other sites can include https://mysite.com/login-zoid-component.frame.js and https://mysite.com/login-zoid-component.popup.js on their pages, and render your component!

Tests

• Edit tests in ./test/tests

• Run the tests:

  npm run test

Testing with different/multiple browsers

npm run karma -- --browser=PhantomJS
npm run karma -- --browser=Chrome
npm run karma -- --browser=Safari
npm run karma -- --browser=Firefox
npm run karma -- --browser=PhantomJS,Chrome,Safari,Firefox

Keeping the browser open after tests

npm run karma -- --keep-open

Publishing

Before you publish for the first time:

• Remove the example code in ./src, ./test/tests and ./demo
• Edit the module name in package.json
• Edit README.md, CHANGELOG.md, and CONTRIBUTING.md
  • The command: npm run version:major will update the version in the package.json by bumping up the major version number. It will also append a new template for this new version at the top of the CHANGELOG.md file so that you can easily write the change log prior to the release.
  • The command: npm run version:minor will do the same for the minor version number, and npm run version:patch does the same for the patch number.

Then:

• Publish your code: npm run release to build and publish a patch version
• Or npm run release:patch, npm run release:minor, npm run release:major

Notes

• webpack.config.js is set up to build both iframe and popup versions of your component. Normally this will be overkill and you'll just want to pick one. The reason there's an example of both is, the popup rendering code adds more to the bundle size, so cutting this out can streamline your bundle if you only need iframe support.

• The karma tests use a mock for the component window (i.e. everything displayed in the popup window or iframe window). This can be seen here. When writing tests which need to consume window.xprops and call callbacks like window.xprops.onLogin(), you'll need to do that here.

• This module imports from zoid/src rather than zoid/dist, allowing your build to take advantage of tree-shaking, flow-types, etc. from zoid and all of its dependencies. That means that various babel plugins etc. that are required by zoid and its dependencies are included in this module. If this isn't to your liking, you're free to switch to zoid/dist, but be warned that you will lose out on some benefits this way. It will reduce the build time though.

• This module is forked from grumbler, which gives a solid (but opinionated) default setup for front-end javascript libraries, including webpack, karma, babel, flowtype, etc. You're free to switch out any of these technologies, but the existing setup is likely to give the best compatibility especially given the previous note around importing from zoid/src.