Merge pull request #35 from HubSpot/bmatto/document-module-routes

Better document module routes

README.md

@@ -1,5 +1,9 @@
 # HubSpot CMS React
 
+## Documentation
+
+Check out an expanded documentation page at [https://github.hubspot.com/cms-react/](https://github.hubspot.com/cms-react/)
+
 ## Welcome!
 
 Thank you for taking the time to learn about HubSpot CMS React. As always our goal is to solve for our customers so we welcome any and all feedback. Chat away in [\#cms-react](https://hubspotdev.slack.com/archives/C04AY1H2204) with other HubSpot developers who are pushing forward with developing with React on the Hubspot CMS.
@@ -31,9 +35,6 @@ If you'd like to get started with your own React module or one of our defaults,
 
 Once the module is uploaded you should be able to see it when you go to edit a page, adding it like any other module.
 
-## Documentation
-Check out an expanded documentation page at https://github.hubspot.com/cms-react/
-
 ## Examples
 
 In this repository is example usage of some of key features of React modules. These examples are are best understood alongside our official [documentation](docs). You can quickly try things out without any local setup by [opening this repo in Codesandbox.io](https://codesandbox.io/p/sandbox/stoic-pateu-g20chg?file=%2Fcms-react%2FREADME.md).

docs/reference/cms-dev-server.md

@@ -21,6 +21,49 @@ You may also start the dev server with the `--ssl` option, which enables:
 - https://cmssite.com.hslocal.net:3000/page
 - https://cmssite.com.localhost:3000/page
 
+## Routes
+
+When the CMS Dev Server for CMS React starts it will look at the directory structure and look for `partials` and `modules` within `components`. It will then dynamically create routes based on what it finds there.
+
+### Modules
+
+The CMS Dev Server offers two different rotes for your modules; `/preview/module/[module_name]` and `/module/[module_name]`.
+
+#### `/preview/module/[module_name]`
+
+You need to be "online" and "authenticated" to use this route.
+
+The `/preview/module/[module_name]` route does talk to the HubSpot backend and behaves similarly to viewing a module in the Design Previewer.
+
+Field values that are used rely on defaults as there is no module instance to pull from. There is no `fields` param available here for overrides.
+
+GraphQL data is derived on the BE and there is no query from the local server to the GraphQL service.
+
+`hublDataTemplate` is supported at this route, the assumed context is similar to that of the Design Previewer.
+
+`Icon`, `CTA`, and other `@hubspot/cms-component` Field helpers are supported at this route.
+
+#### `/module/[module_name]`
+
+The `/module/[module_name]` route is rendered entirely locally without talking to the HubSpot backend.
+
+You can work "offline" and "unauthenticated" at this route - with caveats for GraphQL.
+
+Field values that are used are derived entirely from the Field default values and from parameter level overrides. Param level overrides can be passed via `fields` param which expects stringified JSON of fieldValues that matches what is the passed fieldValues prop (matching the fields definition structure).
+
+GraphQL data in this context is fetched from your local machine using your local access token as the auth for the collector service. These queries are cached, but you can bust the cache with the `hsLocalQueryKey` query parameter.
+
+`hublDataTemplate` is not supported at this route.
+
+`hublParams` at this route will always be an empty object `{}`.
+
+`Icon`, `CTA`, and other `@hubspot/cms-component` Field helpers are not supported at this route.
+
+### Partials
+
+The CMS Dev Server offer a route for partials; `/partial/[partial_file_name]`.
+
+Partials are very thin and do not support GraphQL or `hublDataTemplate`. In the context of the dev server `hublParameters` will always be and empty object `{}`.
 
 ## Storybook