The doc site for Fluxible.
$ npm install
There is also a
/secrets.example.js file that you need to copy to
/secrets.js with your GitHub API credentials to allow the app to access the page content it needs from GitHub.
Run the app
$ npm run dev
This will use
webpack to watch for changes and restart and
rebuild as needed.
To run in production, use
NODE_ENV=production npm run dev. This will use the production
webpack generates. NOTE, this may break your application if the asset hashes
are not on CDN.
How its built
The documentation for the site is generated from the yahoo/fluxible repository. On server start, the docs service, reads the route configuration and leverages the Github API to access the associated markdown document. Each document is parsed and cached. To account for any document updates, we refresh the cache every hour.
Fluxible leverages Atomic CSS to include the minimal set of CSS to style the site. The grunt-atomizer library scans the React components for Atomic CSS classes and builds a CSS file of only the CSS classes that we specify. This keeps the CSS size to an absolute minimum.
Fluxible.io leverages the lunr.js full-text search library to provide client side search functionality.
Creating the index
On server start, the docs service creates a lunr.js index and adds each markdown document to it. The index is then serialized and saved to the
/build/search.json file, so it can be leveraged on the client. The index is about ~1mb in size and too large to dehydrate from the server.
Loading the index
On the client, the Search component has a
componentDidMount lifecycle event which executes the loadIndex action. This action will call the Search service to read the
/build/search.json index file and return that to the action. The
RECEIVE_INDEX action is then fired with this payload, which the
SearchStore listens to and saves the index in the store.
Performing a search
The Search component contains an input field that is displayed when the search icon is clicked. After the search query is entered and
ENTER is pressed, the
navigateAction event is fired to load the new
/search.html page (we use the
navigateAction to save the query in the browser history).
/search.html route uses the showSearch action to dispatch the
DO_SEARCH event with the search query in the payload. The SearchStore uses the query to perform a search on the search index. State is stored and
emitChange is called. The
Docs component listens to change events from the SearchStore and renders the SearchResults component with the search results.
Unit tests can be run via
To run functional tests, ensure you have
$ ./node_modules/.bin/webdriver-manager update --standalone
npm run func to run protractor to execute the functional tests.
The site is hosted on Heroku and requires simple setup to push to the staging server. Check out the gist:
Unless otherwise specified, this software is free to use under the Yahoo! Inc. BSD license. See the LICENSE file for license text and copyright information.