chore: migrate clayui.com to next #5780
Conversation
|
Just an update on this, last week I found a library called mdxts that brings some resources for documentation that we could use here that solves some problems I found, so we can keep some things:
|
|
Well, I sent the commit that implements the use of mdxts to load dynamic documents using the document structure we have today, but it required some changes. It also adds the dynamic Sidebar without having to make manual changes, and an initial implementation to render the Table API still needs adjustments to load the different types of components, which is still causing a bug. With this change, we no longer need to create a separate file to create the examples of the components to render in the document; the table of contents is also generated automatically. At this point, I am only updating the documents for the clay-core package, but I will work on updating the other documents and loading the documents from the other packages. After that, I will be able to work better on the Table API. The site preview is broken because I need to better configure the build in Vercel and it is having some problems because the build root is the site folder but it needs visibility of the files outside of it. But it is working fine in dev when testing locally. |
|
Thanks @matuzalemsteles ! How can I test this. When I run |
@ethib137 oh the link is broken sorry, I have to add a redirect. You can access |
|
Thanks @matuzalemsteles this is looking good. One thing I noticed is the interactive component preview took quite a bit longer to load then it does currently. I thought maybe that's just cause it's on a dev server so I tried, |
@ethib137 Unfortunately this comes from Codesandbox. We use the sandpack that allows us to create component views with the editor and the user can open it in a Codesandbox environment. I tried to use some of the features they have to speed up the loading time but it's not working because it's still experimental. I'm thinking about going back to our old editor without this Codesandbox support. I also found this very slow, and it gets slower because we have to add the component dependencies.
Oh yeah, this is still failing due to external dependencies, I'm looking into that as well. |
|
@ethib137 the build is now working fine on Vercel. https://clay-clayui-com.vercel.app/docs |
hmm... that makes it a tough choice. The open in codesandbox functionality is really quite nice, but the load time is quite annoying. |
Yes, I tried using the url bundler which they say is much faster but unfortunately it doesn't work for our use cases. https://sandpack.codesandbox.io/docs/advanced-usage/bundlers |
https://clay-clayui-com.vercel.app
Well this is a POC that implements the design that I presented a few years ago but still incomplete from clayui.com with the idea of also bringing better documentation for taglibs and improving the existing documentation for React, HTML, CSS and tokens... many of these details were not implemented because it requires a little more work, mainly due to the way we organize the documentation files, which deviates a little from Next.js pattern.
But the idea here is to demonstrate how we can simplify the current implementation today of clayui.com by migrating from gatsby with next.js. There are some things that we would need to implement due to the way we deal with organizing files for documentation. I also didn't go ahead with the integration with LXC because I would need to decide first how we would organize the documents and this affects the route structure but in the end this would be a dynamic route making a call to LXC this would be simpler than in Gatsby which we need organize the data before creating the page.
Another detail is that we can get rid of the thousands of plugins that exist in gatsby that we had to create, which created high complexity for new developers if they want to change or add new things. Next.js also has a better build time because it is incremental, which is a huge benefit for those of us working on documentation.
ISR
ISR is a feature not necessarily from Next.js and Vercel but something that is implemented as a feature and is easy to use, this means that even if we have dynamic routes with LXC they can become static routes and as soon as some content changes we can trigger a revalidation of this page in the background dynamically without the need for a build. There are also other ways of revalidating the page cache such as time, we can define a time if we want to make things simpler, that would be an option.
File System
Well, Next.js creates routes based on the file system within the
appfolder, this is a rule for not only creating routes but also for features such as route streaming, error catching, loading... how we organize documents of the components in each package this would maybe change a little, I'm not sure if it would be possible to do it the same way we do in Gatsby this would change some webpack configs I think this is possible but I don't know how the document routes would work, I would need to investigate this more in depth.MDX
All documents are treated as MDX files so we would move all md files to mdx, we already use mdx files on the current site this wouldn't be a problem.
Currently the Sidebar is created manually, we would need to implement the mechanism to obtain this dynamically so as not to need to add it manually or we can keep it manual so we can organize it the way we want as it is in the DEMO.
Platform
Well, using Next.js also means that we would have to use Vercel unfortunately if we want to avoid problems with builds or surprises... one point is that Vercel's costs seem to be better than Netlify.
Design
This Design is something I worked on some time ago and presented in a document about restructuring the documentation with the intention of improving the Table API, taglibs and component documents.
An important point about this was the idea of building a Table API with more information and also allowing developers to better explore what we expect from the data in a prop.
Another important part is that I am dealing with the website design in a different way with the isolation of the website's CSS to the Clay CSS, this prevents the website's CSS from impacting the document or things related to Clay, we have already had problems with this in clayui .com and I realized that there are still some very subtle ones.