rollback to mdx v1, better docs

docusaurus/docs/vulcan-meteor-legacy/index.md

@@ -12,6 +12,11 @@ Instead, discover our new, shiny framework: [Vulcan Next!](/docs/vulcan-next)
 Vulcan Next is a port of Vulcan, using a more modern framework: Next.js. It includes similar features,
 but with a modern and scalable architecture.
 
+## Transition from Vulcan Meteor
+
+If you were using Vulcan Meteor, check [VulcanJS/vulcan-meteor-next-transition](https://github.com/VulcanJS/vulcan-meteor-next-transition) for a demonstration of using Vulcan Next for the frontend
+and an existing Vulcan Meteor app for the backend.
+
 ## What's Vulcan?
 
 Vulcan is a framework that gives you a set of tools for quickly building React & GraphQL-based web applications. It can handle data loading, e-mail notifications, automatic form generation, and much more, out of the box. 

docusaurus/docs/vulcan-next/features/architecture-and-others.md

@@ -1,21 +1,34 @@
 # Architecture and others
 
+The point of Vulcan Next is to bring everything you need to setup a scalable application, in terms of number of users but also in terms of code. Here is what Vulcan includes:
+
 ## TypeScript
 
+### TypeScript in Next
+
 [Relevant Next doc](https://nextjs.org/docs/basic-features/typescript)
 
-We use TypeScript extensively, and try to enable it wherever possible (sources, Jest, Cypress, Storybook...)
+We use TypeScript extensively, and try to enable it wherever possible (sources, Jest, Cypress, Storybook...).
+
+### Scripts written in TypeScript
+
+What's more annoying than writing an utility script, for instance to clean your database, and being forced to use *JavaScript* or even worse, *bash scripts* :(!
+
+We have created a command `yarn run build:scripts` that builds files from `.vn/scripts/ts-sources` into reusable `.js` scripts. You can reuse
+your code utilities within those scripts. The build script is based on [Tsup](https://tsup.egoist.sh/). It used to be based on Vercel [ncc builder](https://github.com/vercel/ncc), which is however more suited for fully reusable scripts (outside of Vulcan).
+
+### Multiple tsconfig via folder nesting
 
-## Code architecture and build
+The `src` folder has its own `tsconfig.json`: this way collocated files like Stories and Unit tests are correctly handled by your text editor, but they can be excluded from the root `tsconfig.json` to avoid bloating Next.js build.
+
+## Code architecture and build system
 
 ### Code in `src`
 
 All your code should go into the `/src` directory ([doc](https://nextjs.org/docs/advanced-features/src-directory)).
 
 This folder structure is officially supported by Next. It is relevant when you have a lot of development tooling alongside your actual codebase, like we do in Vulcan.
 
-The `src` folder has its own `tsconfig.json`: this way collocated files like Stories and Unit tests are correctly handled by your text editor, but they can be excluded from the root `tsconfig.json` to avoid bloating Next.js build.
-
 ### Package-oriented architecture
 
 The structure of a plugin system of Next is still [under discussion](https://github.com/vercel/next.js/discussions/9133). In the meantime, we strive to provide code as clean as possible, structured in package, so you can easily remove prebundled features.
@@ -25,34 +38,30 @@ You can reproduce the same behaviour with any other prefix by changing `tsconfig
 
 However, you are **not** forced to structure your own code as packages. [Avoid Hasty Abstractions!](https://kentcdodds.com/blog/aha-programming)
 
+### Full-stack NPM packages (advanced)
+
+If you want real NPM packages, you might want to discover the [Vulcan NPM monorepository](https://github.com/VulcanJS/vulcan-npm) where we actually develop Vulcan.
+
 ### Magic src imports with `~`
 
 Import code in `src` from anywhere by writing `import "~/components/foobar"`.
 
 Relative imports are a huge mess to support. A relative import should never go further than the category it belongs too: `pages` should never have to import `components` using a messy `../../../components/myComponent`.
 
-### Scripts written in TypeScript
-
-What's more annoying than writing an utility script, for instance to clean your database, and being forced to use *JavaScript* or even worse, *bash scripts* :(!
-
-We have created a command `yarn run build:scripts` that builds files from `.vn/scripts/ts-sources` into reusable `.js` scripts. You can reuse
-your code utilities within those scripts. The build script is based on Vercel [ncc builder](https://github.com/vercel/ncc).
 
 ### Quasi-imorphism
 
 We allow folders and packages to contain an `index.client` or `index.server` file, that will be used at build time depending on the environment.
 /!\ You still need to have a bare `index` file alongside those environment specific file. Otherwise TypeScript will complain (see the "Learnings" documentation for more details).
 
-#### Env variables in .env
+### Env variables in .env
 
-We demo Next.js 9.4 new feature, `.env` file support. Open `.env.development` to see the default development variables.
+Since Next.js 9.4, `.env` files contain configuration. Open `.env.development` to see the default development variables.
 
 [Official doc.](https://nextjs.org/docs/basic-features/environment-variables)
 
-## Transition from Vulcan Meteor
+Check [our article to learn more about configuration in Next.js](https://blog.vulcanjs.org/how-to-set-configuration-variables-in-next-js-a81505e43dad)
 
-If you were using Vulcan Meteor, check `https://github.com/VulcanJS/vulcan-meteor-next-transition` for a demonstration of using Vulcan Next for the frontend
-and an existing Vulcan Meteor app for the backend.
 
 ## Various
 
@@ -66,12 +75,6 @@ For example, we use it to inject current version into the `html` tag for better
 
 We use [next-sitemap](https://github.com/iamvishnusankar/next-sitemap#readme) to create both the `robots.txt` and `sitemap.xml` in the `postbuild` script.  Change `https://vulcan.next` to your root url in `/vulcan-next-sitemap.js`.  Here's more [configuration options](https://github.com/iamvishnusankar/next-sitemap#configuration-options).
 
-### Performance debugging
-
-[See official doc](https://nextjs.org/docs/advanced-features/measuring-performance).
-
-`DEBUG=vns:perf npm run dev`
-
 ### Auto-changelog
 
 Run `yarn auto-changelog` to compute a new changelog. Works best in combination with `yarn version` (to create git version tags automatically) and `git merge --no-ff your-feature` (to get merge commits).
@@ -89,47 +92,14 @@ See `src/components/ui` for the code, and run Storybook to see the demos.
 
 No more excuses to make dull UIs, you have all the tools you need :)
 
-## Internationalization (i18n)
-
-### next-i18next latest version
-
-Next.js and its ecosystem has made a lot of progress regarding i18n while we were coding VulcanNext.
-We currently use the latest version of [next-i18next](https://github.com/isaachinman/next-i18next) package. 
-Its role is to handle the loading of the right translation files depending on the user current locale.
-
-I18n is a very vast subject, if you need more advanced features, [check Next.js documentation](https://nextjs.org/docs/advanced-features/i18n-routing), it's complete and well written.
-
-You can tweak the configuration to fit your need, see the file named `next-i18next.config.js`.
-
-### No automated redirect
-
-As a default, we disable automated i18n redirect. So a French user
-accessing `/` will still see the page in English. You need to redirect those user manually to `/fr`.
-
-We think that this setup is more consistent, but don't hesitate to tweak the `i18n` config in `next-i18next.config.js`.
-
-### Lang and dir in the custom \_document
 
-`lang` attribute is set automatically by Next.js on `<html>` during server-render/static-render.
-`dir` attribute (`rtl` or `ltr` for right-to-left and left-to-right languages) is set based on the current locale.
-
-
-## MDX support
-
-Get started by reading [MDXJS official doc](https://mdxjs.com/). If you want to write a blog with fancy interactive blocks, you'll fall in love with this feature.
-
-### Next-mdx-enhanced
-
-Thanks to [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote), you can easily use markdown files as your CMS.
-Check the `/docs` page when running the app to see the live documentation.
-
-### MD and MDX import in React
+## Debugging
 
-### Loading MD/MDX in Storybook
+### Performance debugging
 
-Work out of the box. Will however disable default behaviour for ".md" import of Storybook, which is replaced by MDX behaviour.
+[See official doc](https://nextjs.org/docs/advanced-features/measuring-performance).
 
-## Debugging
+`DEBUG=vns:perf npm run dev`
 
 ### Webpack bundle analyzer
 

docusaurus/docs/vulcan-next/features/authentication.md

@@ -1,16 +1,30 @@
 # Authentication
 
-**Draft documentation**
+## Custom app-level setup
 
 We use stateful, token-based (with symmetrical encryption) password-based authentication.
 
 At the time of writing (2021 11), authentication is used only to protect API routes.
 You don't really need to protect web pages, redirections based on the `useUser` hook 
 are sufficient.
 
-We will introduce _middlewares later on for protecting web pages, but think of it as
-a very advanced feature (it serves only to protect sensitive content such as paid pages, and
-even then you don't really need this feature, it's just a perf optimization).
+We will introduce [Middlewares](https://nextjs.org/docs/advanced-features/middleware) later on for protecting web pages, but think of it as
+a very advanced feature. It serves only to protect sensitive content such as paid pages, and
+even then you don't really need this feature, it's just a perf optimization.
+
+## Why no reusable packages?
+
+Vulcan has been there for a long while, and we've seen it all. We are still disatisfied by the state of the art. Many reusable libraries have popped up over time, from [Meteor accounts](https://docs.meteor.com/api/accounts.html) system to [Account-js](https://www.accountsjs.com/) and now [Next auth](https://next-auth.js.org/).
+
+None of them is canonical, none of them is really easy to use, because none of them is based on any actual kind of standard. [You can help us fix that by contributing to our research here.](https://github.com/lbke/research/blob/main/auth.md)
+
+They are certainly working very well, but they are not transparent on the way they work under the hood: are tokens stored in HTTP cookies or localStorage? What algorithms are used? Are they symmetrical or not, can you check auth without a server, will they call a database???
+
+With a custom implementation, you have full control over these factors. We prefer transparent code over reusable blackboxes. However, we still recommend [Next Auth](https://next-auth.js.org/) if you believe it's a fit for you.
+
+## Passport authentication
+
+See the home page footer to access signup, login, logout and profile page. Implementation is based on Next official example [with Passport and Next Connect](https://github.com/vercel/next.js/tree/canary/examples/with-passport-and-next-connect)
 
 ## Flows
 
@@ -50,3 +64,9 @@ fall into this category, so we prefer using more basic, independant, REST endpoi
 ## UI
 
 We provide basic UI in the `/pages/account`.
+
+## Experimental SSR redirection (deprecated)
+
+*This feature is experimental and not useful in most scenarios.* We advise to stick to client-side only patterns. [See relevant issue](https://github.com/VulcanJS/vulcan-next/issues/71).
+
+See `src/pages/vn/debug/private.tsx.old` for a demo. You can use `withPrivateAccess` HOC to make a page private and handle redirections correctly in all situations (server-side, client-side, in the context of a static export etc.).

docusaurus/docs/vulcan-next/features/graphql-client.md

@@ -4,14 +4,8 @@
 
 ### Apollo Client setup based on official with-apollo example
 
-See [official example](https://github.com/vercel/next.js/blob/canary/examples/with-apollo)
+See [official example](https://github.com/vercel/next.js/blob/canary/examples/with-apollo).
 
-### Deprecated isomorphic setup
-
-See branch `example/apollo-ssr-and-server-redirect` for a previous setup of Apollo. It demoes a powerful setup that can handle Apollo with SSR and authentication.
-However, this architecture led to a HUGE increase of complexity for a very low perceived values.
-We dropped it in favour in an "opt-in" approach of Apollo SSR and a client-only pattern for authentication management similar to Vercel's dashboard architecture.
-See [Public is the new private ticket](https://github.com/VulcanJS/vulcan-next/issues/71) for more details.
 
 ### Optional, per-page Apollo Provider and SSR
 
@@ -27,11 +21,18 @@ With have a non-regression test for SSR, so no surprise with component that sudd
 
 ### Pass cookies to Apollo client during server render
 
-This allow to make authenticated calls
+This allow to make authenticated calls.
 
 ### Cross-domain connection
 
 Enable NEXT_PUBLIC_CROSS_DOMAIN_GRAPHQL_URI=1 to connect to APIs from 3rd party applications. This is useful if you must connected
 to an existing Vulcan graphql API (a legacy Meteor API, another Vulcan Next application, or a Vulcan Express backend).
 
-In particular, this will enable crendentials inclusion so login cookie works as expected.
+In particular, this will enable crendentials inclusion so login cookie works as expected.
+
+### Deprecated isomorphic setup
+
+See branch `example/apollo-ssr-and-server-redirect` for a previous setup of Apollo. It demoes a powerful setup that can handle Apollo with SSR and authentication.
+However, this architecture led to a HUGE increase of complexity for a very low perceived values.
+We dropped it in favour in an "opt-in" approach of Apollo SSR and a client-only pattern for authentication management similar to Vercel's dashboard architecture.
+See [Public is the new private ticket](https://github.com/VulcanJS/vulcan-next/issues/71) for more details.

docusaurus/docs/vulcan-next/features/internationalization.md

@@ -0,0 +1,23 @@
+# Internationalization (i18n)
+
+## next-i18next latest version
+
+Next.js and its ecosystem has made a lot of progress regarding i18n while we were coding VulcanNext.
+We currently use the latest version of [next-i18next](https://github.com/isaachinman/next-i18next) package. 
+Its role is to handle the loading of the right translation files depending on the user current locale.
+
+I18n is a very vast subject, if you need more advanced features, [check Next.js documentation](https://nextjs.org/docs/advanced-features/i18n-routing), it's complete and well written.
+
+You can tweak the configuration to fit your need, see the file named `next-i18next.config.js`.
+
+## No automated redirect
+
+As a default, we disable automated i18n redirect. So a French user
+accessing `/` will still see the page in English. You need to redirect those user manually to `/fr`.
+
+We think that this setup is more consistent, but don't hesitate to tweak the `i18n` config in `next-i18next.config.js`.
+
+## Lang and dir in the custom \_document
+
+`lang` attribute is set automatically by Next.js on `<html>` during server-render/static-render.
+`dir` attribute (`rtl` or `ltr` for right-to-left and left-to-right languages) is set based on the current locale.

docusaurus/docs/vulcan-next/features/mdx.md

@@ -0,0 +1,14 @@
+# MDX support
+
+Get started by reading [MDXJS official doc](https://mdxjs.com/). If you want to write a blog with fancy interactive blocks, you'll fall in love with this feature.
+
+## Next-mdx-remote
+
+Thanks to [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote), you can easily use markdown files as your CMS.
+Check the `/docs` page when running the app to see the live documentation.
+
+## MD and MDX import in React
+
+## Loading MD/MDX in Storybook
+
+Work out of the box. Will however disable default behaviour for ".md" import of Storybook, which is replaced by MDX behaviour.

docusaurus/docs/vulcan-next/features/mongo-graphql-backend.md

@@ -1,16 +1,11 @@
 # GraphQL Server + Mongo
 
-## Authentication
+## Vulcan Fire
 
-### Passport authentication
+🔥[Vulcan Fire](../../vulcan-fire) is our internal CRUD engine. It lets you setup the most basic operations very easy for any kind of data model.
+A simple blog requires at least a dozen GraphQL resolvers: let Vulcan do the hard work!
 
-Access the See the home page footer to access signup, login, logout and profile page. Implementation is based on Next official example [with Passport and Next Connect](https://github.com/vercel/next.js/tree/canary/examples/with-passport-and-next-connect)
-
-### Experimental SSR redirection
-
-*This feature is experimental and not useful in most scenarios.* We advise to stick to client-side only patterns. [See relevant issue](https://github.com/VulcanJS/vulcan-next/issues/71).
-
-See `src/pages/vn/debug/private` for a demo. You can use `withPrivateAccess` HOC to make a page private and handle redirections correctly in all situations (server-side, client-side, in the context of a static export etc.).
+More info in the [live learning tutorial](https://vulcan-next.vercel.app/learn) or in [Vulcan Fire docs](../../vulcan-fire).
 
 ## Apollo Server
 

docusaurus/docs/vulcan-next/features/smart-components.md

@@ -19,6 +19,6 @@ For the `Article`, it could be the title, content, and the author unique id.
 Based on the `SmartForm`, it's possible to spawn a full admin area for all the models of your application.
 As easy as writing a loop!
 
-You can see a demonstration of this approach in `src/pages/admin`, or in your application by opening
-`http://localhost:3000/admin`.
+You can see a demonstration of this approach in `src/pages/vn/admin`, or in your application by opening
+`http://localhost:3000/vn/admin`.
 

docusaurus/docs/vulcan-next/features/testing-+-storybook.md

@@ -7,22 +7,27 @@
 We support server and client testing based on the following naming convention:
 
 - A test named `myTest.test.ts` will be executed in a JSDOM environment (~ like a browser). Use as a default for React components and generic utility code.
-- A test named `myTest.test.server.ts` will be executed only in the Node server environment. Use to test your Graphql resolvers for instance.
+- A test named `myTest.test.server.ts`, or any test located within a `server` folder, will be executed only in the Node server environment. Use to test your Graphql resolvers for instance.
 
 ### React Testing library
 
 We have preinstalled [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) and [React Testing Hooks](https://github.com/testing-library/react-hooks-testing-library).
 
 ### Tests for Vulcan Next (for contributors only)
 
-We have a unit tests for some key features and scripts of VN, through the `tests/vns` folder.
+We have a unit tests for some key features and scripts of VN, through the `tests/vn` folder.
 
 This folder is ignored when running `yarn run test:unit`, to avoid bloating your own tests.
 
 ### MDX parsing, magic imports with ~
 
 [jest-transformer-mdx](https://github.com/bitttttten/jest-transformer-mdx) allow importing .mdx also in Jest
 
+### .env support
+
+Load `.env` config automatically in Jest,
+see [Jest globalSetup](https://github.dev/VulcanJS/vulcan-next/blob/main/.vn/tests/globalSetup.js).
+
 ## Unified testing patterns
 
 We strive to unify testing patterns between Cypress and Jest where it makes sense.

docusaurus/docs/vulcan-next/features/zz-not-yet-implemented.md

@@ -27,10 +27,6 @@ Setup debug client side programmatically based on DEBUG environment variable
 
 Splitting tests in folders? In order to differentiate real e2e tests from integration testing
 
-## Jest
-
-Load .env development config automatically in Jest
-
 ## GraphQL
 
 Graphql code generator for better autocompletion
@@ -39,6 +35,7 @@ Demo support of multiple graphQL API using Link split
 ## Next
 
 Remove debug routes from bundle during build
+=> we currently protect them with a middleware
 
 ## Others
 

starters/next/next.config.js

@@ -8,6 +8,9 @@ const withMDX = require("@next/mdx")({
   options: {
     jsxRuntime: "automatic",
   },
+  // TODO: upgrade to v2 https://mdxjs.com/migrating/v2/
+  // Currently (05/2022) we are blocked by Storybook which
+  // doesn't support mdx v2
 });
 
 // Custom config from vulcan-next

starters/next/package.json

@@ -100,8 +100,8 @@
     "@graphql-tools/merge": "^8.2.11",
     "@graphql-tools/schema": "^8.3.11",
     "@hapi/iron": "6.0.0",
-    "@mdx-js/loader": "^2.1.1",
-    "@mdx-js/react": "^2.1.1",
+    "@mdx-js/loader": "^1.6",
+    "@mdx-js/react": "^1.6",
     "@mui/icons-material": "^5.0.0",
     "@mui/material": "^5.0.0",
     "@next/mdx": "^12.1.6",