By virtue of a relatively simple `hexo-browsersync` package[0], which
implements BrowserSync[1] in Hexo, this change brings support for automatically
reloading the browser when the source content has changed.
No more pressing "Reload" in order to see the changes to the Markdown source
when working on documentation! 🎉
[0]: https://npm.im/hexo-browsersync
[1]: https://www.browsersync.io
<!--**Pull Request Labels**
While not necessary, you can help organize our pull requests by labeling this issue when you open it. To add a label automatically, simply [x] mark the appropriate box below:
- [ ] feature
- [ ] blocking
- [ ] docs
To add a label not listed above, simply place `/label another-label-name` on a line by itself.
-->
# Testing React Apollo
This is a guide specifically for testing React Apollo. Based off of @excitement-engineer's (great) original work [in this PR](https://github.com/apollographql/apollo-client/pull/3309).
**A few notes:**
- I'm keeping this separate from server testing, since combined I think they'll be too long. **I'm open to discussion on this, though**.
- I added the guide here rather than React Apollo's docs, since I feel like we have a good set of `guides` here, and would hate for this to be missing. I also feel like the view logic may transfer to other UI integrations, but I don't have a lot of insight into that.
- I went with using `wait(0)` instead of refactoring and counting renders like some other exmples do, for simplicity. I wanted to lower the barrier of entry for testing as much as possible.
- I used `react-test-renderer` instead of Enzyme or anything else, just to keep the toolset as simple as possible.
The default syntax highlighting provided by Hexo uses highlight.js. While
there are a number of great syntax highlights provided by highlight.js, some of
the more important ones to the Apollo project: `graphql`, `typescript`, and
`jsx` are notably missing.
This uses the `hexo-prism-plus` plugin for Hexo, along with some upstream
configuration to `apollo-hexo-config`[0] and `meteor-theme-hexo` (previously
named `hexo-theme-meteor`)[1]. See refs for more information!
[0] https://github.com/apollographql/apollo-hexo-config/commit/547107b0
[1] https://github.com/meteor/meteor-theme-hexo/pull/61
This the reason for this unneeded dependency traces back to the `api-box` on
https://github.com/meteor/docs, though its dependency hasn't been necessary on
any other docs deployment, including this one, since then.
Rather than developing the theme on individual docs deployments, that work
should now be done on the theme repository[0] and the example doc
deployment[1] since those repositories contain the infrastructure for testing
and deploying changes across all docs properties. More information on
developing the theme can be found on those repository's `README.md`s.
[0] https://github.com/meteor/hexo-theme-meteor
[1] https://github.com/meteor/theme-example
While I'm aware of the need for the `showdown` package for rendering some
content on the Meteor Docs, I'm not aware of any Apollo repository that uses
it. I've searched through the source, and cannot find any usage.
If there is a repository that uses it directly (in its `scripts/` directory),
it should be switched to using a plugin, which can explicitly declare
`showdown` as a dependency, rather than depending on it at the root of the
repository. (This is how `hexo-typescript-api-box` does it on the
`apollo-client` docs, which has correctly removed the direct dependency.)
Luckily, these repositories now have tests so if any of these fail, we should
know pretty easily and be able to add the dependency back to just those that
need it.
Generators are used for generating additional content in Hexo. While these
are great for making a blog (for example, `hexo-generator-index` to put all
your blog posts on an index page, `hexo-generator-tag` to keep a page updated
with all your trending blog tags, and `hexo-generator-archive` if you want to
store your aging content somewhere where nobody will find it), they don't seem
to be at all necessary for our purposes, which are documentation.
Unfortunately, they are in the default skeleton of a new Hexo project and they
don't seem to have ever been removed from our non-blog docs deployments,
despite the fact that they seem unnecessary.
In an effort to drastically reduce the overhead of maintaining these docs
deployments, I'm removing these as "unnecessary" until proven otherwise.
The theme which the docs in this repository are based on
([`hexo-theme-meteor`](https://github.com/meteor/hexo-theme-meteor)) has been
published to npm.
Additionally, most of the configuration which was once present in this
repository's `_config.yml` file, has been moved into an Apollo-centric theme
configuration npm,
[`apollo-hexo-config`](https://www.npmjs.com/package/apollo-hexo-config) (and
similarly, [GitHub](https://github.com/apollographql/apollo-hexo-config)).
The theme bundled in this npm is a converged version of the two `apollo`
and `master` branches on the `hexo-theme-meteor` repository, which is a result
of the work undertaken in https://github.com/meteor/hexo-theme-meteor/pull/51.
Lastly, this makes use of a new `chexo` npm which acts as a wrapper for `hexo`
but permits the use of an inherited configuration from npm, rather than a
statically defined CLI file parameter (previously with `--config a,b`).
It's safe to mark all dependencies of this theme as 'dev' dependencies, as
none of them are needed to be installed in a production setting.
This was done automatically, so in some cases, this merges existing
`devDependencies`, and may also have added a missing `nodemon` `devDependency`
in cases where it was missing. In other cases, this commit may not have
made such a change.
Most notably to update `ejs` and quell the vulnerability warning on
GitHub, which had a low probability of being problematic as the usage
here is for a statically generated site.
