[v2] Proposal: Official CodeSandbox Template

[Saeris]

Hi there! I'm part of the team over at @codesandbox and we've recently been working on a new feature set that allows our users to create their own custom Templates, which like our official templates allows them to quickly start a new project from pre-configured boilerplate code. This functionality is similar to what you might find in a CLI scaffolding tool, such as the one Docusaurus v2 features.

Recently I took the time to see if Docusaurus v2 would run inside of our container sandboxes, which it indeed does with the minor addition of a sandbox.config.json to specify the execution environment (without it, our GitHub importer defaults to react based on the project's dependencies). You can check out an example template here:

https://codesandbox.io/s/docusaurus-template-8hm7z

This template was created by first using our GitHub importer, which allows us to take the content of any repository or a subfolder within a repository to quickly create a new sandbox. In this case, I simply ran your CLI tool to generate the new project files and added the above mentioned config file. Here's an example from our templates repository and an import link to create a new sandbox from that repo:

https://github.com/codesandbox/codesandbox-templates/tree/master/packages/container/docusaurus-template

https://codesandbox.io/s/github/codesandbox/codesandbox-templates/tree/master/packages/container/docusaurus-template

One of our goals with Templates is that we want to empower framework developers to quickly add and maintain their own templates inside of CodeSandbox, which the community can then subscribe to in order to quickly create new sandboxes. We're still nailing down the exact flow for linking a Template to a GitHub repository, but it is a key milestone on our roadmap as our plan is to move all of our official templates to repositories. The goal here is that we want to provide a better experience for users by allowing both framework maintainers and the open source community to quickly make updates and resolve issues without necessitating involvement on our part.

So as far as my proposal goes, Docusaurus could create and maintain their own custom template by adding a new package to the packages directory of this repository, which would contain the output from the CLI plus the required config file, similar to the example linked above. I'll keep in contact and provide support in setting up a template based on that package once everything is in place on our end. From there, it would be the Docusaurus team's responsibility to keep that package up to date, which would keep the linked template up to date as well.

I would very much like to hear your thoughts on this! Any feedback you might have would be highly appreciated!

[endiliey]

@Saeris is it possible to sync it with the template hosted in our repo ? https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-init/templates/classic

Otherwise it seems that we have to keep sending PR to that repo to be in sync

[Saeris]

@endiliey a quick glance indicates to me that it could be possible. The only thing missing that's a requirement is the sandbox.config.json which is required to break out of environment auto-detection to use a node container environment. If it's not too big of a deal to add that to the template, then yes you can just use that.

While not all of your users would want to use CodeSandbox, having that config file will make it easy for them to import their project should they want to.

[Saeris]

@endiliey also the idea here is that your team would maintain the template repo instead of us. I plan to delete the directory in the repository I linked in the original post at a later date. It's just there for now to explore a proof of concept.

[endiliey]

also the idea here is that your team would maintain the template repo instead of us. I plan to delete the directory in the repository I linked in the original post at a later date. It's just there for now to explore a proof of concept.

Good idea. Actually that's what we wanted. We want the actual push access to maintain a template repo. Otherwise sending PR to keep it in sync will be very slow.

Will there be a codesandbox organization repo for templates maybe ? or maybe we can create our own cc @yangshun @wgao19

[Saeris]

We don't want our users to have to rely on us at all as far as linking a template to a github repository goes. You can literally use the template hosted in your repo which you linked above and all you should need to do to have it published inside CodeSandbox as a custom template is:

1. have the required config file in the repo,
2. through our app, define a new custom template and link the sandbox to that repository.

To clear up any misunderstanding, right now the templates we list inside the create sandbox modal under the Client and Container tabs are the "official" templates which we maintain, which we want to move away from. The next step for our rollout of custom templates is to provide users the ability to follow custom templates created by other users, and along with that we're going to build out a community page where you can search for and follow community created templates, which will show up under their own tab in the create sandbox modal. This way users can curate which templates they want to use and anyone can publish their own.

It's simply too cumbersome to maintain a list inside of our organization's repos. Ideally we would like to transfer stewardship of the existing "official" templates to the maintainers of their respective frameworks, however in some cases (primarily "Client" templates), this isn't possible yet because they rely on some custom execution logic which we refer to as "environments".

Docusaurus, however, runs inside of our node environment because it relies on complex build tooling to generate site content. Gatsby works in the same way. It would be infeasible to run the entirety of Gatsby's build process inside the browser, that's why we have it running inside of a docker container instead.

As another example, React is a client template, meaning we compile everything inside the browser. A common misconception is that it's being compiled by react-scripts since it's based on create-react-app. Since we have to maintain that execution environment ourselves, it's not currently possible to transfer maintenance of our React template to the React team. In the future we may have a system that will allow users to build their own client execution environment, but for now all custom client templates must be based on one of the existing official client templates (this is where template auto-detection comes in, our GitHub importer infers what execution environment to use based on dependencies).

Fun fact: the React template (and some others) aren't linked to a repository at all. They're actually sandboxes on @CompuIves's account. Meaning any time there needs to be a change to the boilerplate files for that template, he has to edit them manually through the app! Back when I first started playing around with CodeSandbox, I actually spent hours digging through the repo trying to find where all those boilerplate files were without any luck.

[endiliey]

To clear up any misunderstanding, right now the templates we list inside the create sandbox modal under the Client and Container tabs are the "official" templates which we maintain, which we want to move away from. The next step for our rollout of custom templates is to provide users the ability to follow custom templates created by other users, and along with that we're going to build out a community page where you can search for and follow community created templates, which will show up under their own tab in the create sandbox modal. This way users can curate which templates they want to use and anyone can publish their own.

Sounds good. been wondering on how those 'official' templates got picked

It's simply too cumbersome to maintain a list inside of our organization's repos. Ideally we would like to transfer stewardship of the existing "official" templates to the maintainers of their respective frameworks, however in some cases (primarily "Client" templates), this isn't possible yet because they rely on some custom execution logic which we refer to as "environments".

I agree !

Well i guess the path forward now is just for us to maintain our own template and add the required config and publish it as codesandbox template.

[Saeris]

Yeah I'll keep you posted about when we roll out the publishing features!

As for the "official" templates, those were all added by request or on our own initiative. In the future the way we list them may change, as it would make more sense to flag custom templates through an admin interface rather than hard-code them into the app as we do now. Flagging a template as "official" could be thought of as like a user verification system like on Twitter. There's for sure a lot of room for improvement in this area!

[slorber]

Hi @Saeris. I'm late to the party, but found this issue interesting and would like it to be completed.

Do you still work for CodeSandbox?
Do you have any up-to-date news to share about how we could create an official Docusaurus template on CodeSandbox?

As we have MLH interns joining us, that could be a nice task for one of them.

[Saeris]

Hey @slorber! Yeah I'm no longer officially with the team at CodeSandbox, however I can still be of help. We actually shipped the ability for anyone to create and share their own templates with the community a while back, so it's actually quite easy to publish and maintain an official template on your end. Here's some reading on that subject:

https://codesandbox.io/post/hello-template-universe-goodbye-project-setup

https://codesandbox.io/docs/templates

When you create a template, you can set it's visibility to public, which means that it will show up in the Create Sandbox wizard under the Explore tab when a user searches for "docusaurus". That's one way to go about it.

Alternatively, CodeSandbox treats all GitHub imported sandboxes as templates (more on that here), so for a project like this I would go with either creating a separate template repository or an example/demo folder in this one which can be imported using the GitHub Import Wizard. The only extra step you should need to make that work is to add a sandbox.config.json configuration file in the root folder of the example project. That file is used by CodeSandbox to configure the editor environment and override the default sandbox execution environment detection. In this case, you want to specify that this is a node template. While CodeSandbox uses some heuristics to figure this out on it's own, a lot of the time it defaults to create-react-app, which wouldn't work for this particular project. Here's the config from the example template I linked in my original post;

{
  "infiniteLoopProtection": true,
  "hardReloadOnChange": false,
  "view": "browser",
  "template": "node"
}

To get the template you create added to one of the curated lists in the Create Sandbox Wizard, you would need to reach out to the folks at CodeSandbox directly and request it. Opening an issue in their repository should work. Include a link to the template you create in that post.

So to summarize that in a few steps:

1. create a template repository or example/demo folder in this repository
2. place the starter files there (whatever the default files for a new docusaurus app are)
3. create a sandbox.config.json and place it in the same root directory as the starter files
4. verify that that repository can be imported using CodeSandbox's import wizard
5. copy the link to that GitHub imported sandbox
6. file a new issue requesting that sandbox be added to one of the curated sandbox lists

To maintain that template, all you should need to do is commit changes to the files created in step 2. Those changes will be picked up by CodeSandbox automatically, no further interaction with their team should be necessary.

Hope that helps!

[slorber]

Thanks for all these infos @Saeris 👍

What I think we could do is:

• Use our docusaurus-init cli to create the ./codeSandboxTemplates/docusaurus-init folder
• Add ./codeSandboxTemplates/docusaurus-init/sandbox.config.json
• Ensure the template dependency versions are bumped when we release new versions to keep it up to date
• Have a command to "regen" the template from the docusaurus-init cli, so that it's kept up to date from time to time (we don't change the init template very often)

Also, I'll see if we could get a docusaurus.new domain registered that link to that code sandbox.

Does it make sense to you?

[Saeris]

That sounds good to me! Let me know if you have any other questions and I'll do my best to come up with solutions.

[sammychinedu2ky]

I'm going to work on this issue

[sammychinedu2ky]

#3717

[slorber]

Let's keep it open for now, as we need:

• Add documentation, highlight the ease to try Docusaurus (why not embedded codesandbox in Docusaurus 🤪 )
• Ask for adding it to official templates (Add Docusaurus to official templates codesandbox/codesandbox-client#5135)
• docusaurus.new domain?

[sammychinedu2ky]

Awesome. So I guess I would have to wait till it's ready before I document. Since I would be making reference to the official template in codesandbox during documentation

[sammychinedu2ky]

Ask for adding it to official templates
Please is there any update on adding Docusaurus to the official templates on CodeSandbox?

[slorber]

@sammychinedu2ky unfortunately no 😅

I don't have more infos that what is written here: codesandbox/codesandbox-client#5135

[sammychinedu2ky]

chai... ok I just made a comment on the issue you linked 😅

[slorber]

Hi @sammychinedu2ky

Until the CodeSandbox PR is merged, I was able to get a subdomain redirecting to the up to date classic template: https://new.docusaurus.io

If you want to add some doc about it let me know, otherwise, I'll do it within next week.

[sammychinedu2ky]

Alright thanks for the update. I would work on that😁