feat(docs): demo

[vejja]

Types of changes

• Bug fix (a non-breaking change which fixes an issue)
• New feature (a non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Description

This PR allows to deploy our Documentation site under the protection of our own Security Module.

The intention here is twofold:

1. Provide a live demo, based on Nuxt-Security's Documentation, of the capabilities of the module.
   Currently, our Documentation pages are deployed on Vercel as a standalone website that does not use the Nuxt Security module.
   With this addition, we can now deploy the Documentation pages on Vercel but with the Nuxt Security module. We can showcase this deployment to demonstrate how Nuxt Security protects our own Documentation pages

2. Provide a challenging playground environment for us internally.
   Currently, we are sometimes facing issues that can only be observed in highly complex environments using many external modules.
   Our Documentation pages are a typical example of a complex environment : it is based on the Nuxt Docus theme, which itself is based on Nuxt-Content, which under the hood leverages many additional modules (e.g. VueUse, MDC, Tailwind, Stackblitz etc.)
   With this PR, we can now verify how Nuxt Security interacts with a typical Nuxt-generated application, both locally during development, and in production on a live Vercel deployment.

Please note the architecture proposed here:

• we are not polluting the /docs folder: Documentation deployed from /docs is unchanged, i.e. does not include Nuxt Security
• we are introducing a /demo folder: This folder extends the /docs folder, and adds nuxt-security to it. Documentation deployed from /demo will include Nuxt Security. The version of nuxt-security that is used is the one in the current branch being tested (i.e. we locally compile the module from source rather than fetching it from NPM)

With this setup, we ensure that our Documentation stays always available for our end-users, regardless of the latest changes we make to the module locally.

Checklist:

• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes (if not applicable, please state why)

This PR does not make changes to the module sources
This PR provides a README in the /demo folder to assist with deployment on Vercel

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
nuxt-security	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Nov 10, 2023 11:03am

[Baroshem]

Hey @vejja

This is a really interesting addition to the module. I can totally see the use cases of it.

I wonder however if the documentation is a good example for testing more advanced scenarios (it is documentation after all).

Maybe we could prepare some dummy application like a blog and more advanced like movies app where this module could really shine?

I am not saying that it is a must. Just wondering what are your thoughts about that as you are an expert in it :)

[Baroshem]

Hi @vejja

If you dont mind. I would like to release a new RC version today without this feature. We have gathered a lot of features and fixes already and I would like to publish them as separate versions.

So for this, I would love to have it in rc.4 :)

[vejja]

Hey @vejja

This is a really interesting addition to the module. I can totally see the use cases of it.

I wonder however if the documentation is a good example for testing more advanced scenarios (it is documentation after all).

Maybe we could prepare some dummy application like a blog and more advanced like movies app where this module could really shine?

I am not saying that it is a must. Just wondering what are your thoughts about that as you are an expert in it :)

Yes you're right
I did it on docs because it was already there, so that was an easy playground to replicate - nothing new to build
Just took the quickest available path TBH 😂

[Baroshem]

question: would you like me to deploy these documentation pages on my Vercel account? Or will they be updated after I merge the code to the repo?

[vejja]

They won't be updated because I set up my own Vercel configuration so that it only deploys from the demo-docs-security branch.
I think it's better if you own these pages anyway.
I just cancelled these domain names from my account so that you can take over them.

[Baroshem]

Ok, maybe I will also change their names to for example nuxt-security-ssr and nuxt-security-ssg?

[Baroshem]

I have also been thinking about maybe adding info about these demo apps to the documentation itself?

So that user can easily check both of them and how they are deployed to production.

What do you think?

[vejja]

BTW feel free to not merge this PR if you think it's polluting the overall codebase.
I thought about your comments and I think you're right. After all, we can keep this as a separate branch for us internally to make tests.

[vejja]

I have also been thinking about maybe adding info about these demo apps to the documentation itself?

So that user can easily check both of them and how they are deployed to production.

What do you think?

Yes ok, like a new section in the docs 'Demo' or 'Check it live' that tells the user to click on the links and open their devtools to observe headers?

[vejja]

Although the more I think about it, isn't that going to confuse the average user ?
The guy is scrolling the docs and we redirect him on a clone of the docs with nuxt-security 🤯
That's why your idea of having a specific demo app (e.g. movies) is maybe cleaner? That's a lot of work though, unless we can fork some existing example. Let me know

[vejja]

ok now I think I might have an idea of how to make this easily

1. We fork Nuxt Movies
2. We modify the fork to make it an extendable theme
3. We modify demo to extend that fork instead of extending docs 

Update: even easier (no need to use extensions - only drawback is the repo will now contain a full copy of Nuxt Movies, but who cares?)

1. We fork a copy of Nuxt Movies directly inside demo
2. We add nuxt-security to it

That's it. This way we can both

• play locally with demo during dev based on the current state of nuxt-security in dev
• deploy a demo based on Nuxt Movies as a showcase to the users with links in the docs, but based on the latest released version.

WDYT? Is it worth the effort you think?

[Baroshem]

I would say that it is a much better idea!

It also showcases another Nuxt example project that covers good practices and patterns.

There are two example apps that we should be able to easily showcase as demos:

1. https://github.com/nuxt/hackernews
2. https://github.com/nuxt/movies

i think this could make a better example/demo showcase of how the user could setup their application (whether it is a SSG or SSR) based on our recommendations.

I would recommend creating a folder called demo and inside of it have two folders for both movies and hackernews applications named ssr & ssg. They could be then deployed from my Vercel account with appriopriate names like (nuxt-security-ssr and nuxt-security-ssg) and then, we could easily link them in our documentation and readme for both users and us to test out :)

But I wouldn't spend that much time on developing these applications. Just take one or two, add nuxt-security into them and push them to this or new branch so that I could deploy them and link in the docs. This should be enough for both us and users to test NuxtSecurity in battle :)

Let me know what you think about it.

[Baroshem]

Hey @vejja

Are you working on something else here? Not sure if I should review it right now or is it still in progress?

[vejja]

Hey @Baroshem
Yes in fact I've been trying to add Nuxt Movies and Hackernews as we were discussing, and also to create CSP end-to-end tests in the browser using Playwright but it's not that straightforward.
Nuxt Movies and Hackernews do not support SSG, and Playwright does not catch CSP issues in an easy way.
I am going to close this PR, and if I manage to find time to get around these issues, I will re-submit later.

[Baroshem]

Ok, clear!

Thanks for your work! I really appreciate it! 💚