Over the last year and a half Fractal has evolved from an internal prototype at Clearleft into an open source project that we (and now many others) are using to create and manage component libraries. It’s been exciting to get validation of the core ideas behind the project and great to see all the different ways that others have been pushing at the boundaries of what is currently possible with it.
When we were developing Fractal our goal was to create a component library tool that was as agnostic as possible to things like build tool and template language choices, and also offer opportunities to build upon the core feature set to allow better integration and custom workflows for development teams. To some extent I think that we were successful in this; but it is also clear from the feedback over the last year or so that there is plenty of room for improvement!
After seeing how people are trying to fit Fractal into their development process, and thanks to some great input from the community, I’ve identified the following key areas to work on improving in 2017. Please chime in on the comments if you think I’ve missed anything!
The following are fairly loose ideas on potential areas of improvement with regards to the core functionality and general usability of Fractal. More detailed RFC-style issues may be posted separately for proposed improvements that warrant further technical discussion.
A number of great suggestions for potential improvements to the way that components are created and handled by Fractal have come up in the past year. The current system has proven to be able to serve a lot of fairly disparate use cases, but not always without compromising the clarity of the component configuration or the structureorganisation of view templates and their partialsincludes.
At Clearleft we have also been talking a lot about how we might be able to use component libraries earlier on in the design/build process, perhaps by creating ‘placeholder’ components that do not have any code yet, but do have a README or a static mockup of a component. In this way you could quickly scaffold out a component library structure, and iterate on the organisation and design even before adding a line of code. Components could then be built out with the templates and other assets as the project progresses.
A detailed list of proposed improvements to the component system (with more technical detail) will be published as a separate issue for people to comment on. However the main suggestions will include:
The current documentation system is based on the same filesystem parsing, configuration logic and template engine handling as the component system is. The aim was to allow people to use a mix of markdown and templating language features to build docs and ‘styleguides’ that would complement the component library.
Whilst people have indeed been creating some nice examples of documentation/styleguides, the process is currently hampered somewhat by the lack of a standard ‘UI library’ of style guide components (such as colour swatches) and the inability to easily add custom styles to the documentation in the web UI. Additionally, the documentation system lacks ‘knowledge’ of the component library itself, which means that things like generating links to components, rendering components within the documentation or displaying ‘live’ information about components is currently not straightforward and requires significant technical knowledge.
Creating a UI library of ‘partials’ for style guide components and even helpers for linking to/displaying components is partly a significant challenge because of the flexibility Fractal offers when it comes to template engines and organisation of the component library.
While it’s clearly a key feature that Fractal supports multiple template languages for creating components, the use case for supporting the same functionality for the documentation generation is less clear. I propose switching Fractal to enforcing use of a single predetermined template engine (most likely Nunjucks) for generating documentation. This would make it considerably easier to create and document a canonical set of partials for creating styleguides/docs, and to tie in the components in the component library much more closely into the docs to allow for easier linking and embedding etc. This simplification would benefit less technical users of Fractal.
The current model of theming was intended to give a lot of power to people that wanted to develop completely custom themes (right down to the URLs), completely distinct from the default ‘Mandelbrot’ theme that ships with Fractal. However, this was somewhat at the expense of making it really easy to customise the ‘look and feel’ of the theme itself without a fair bit of technical knowledge.
Since releasing Fractal, there has been considerable interest in customising the Mandelbrot theme, and very little interest in developing completely custom themes. This is understandable; Mandelbrot does a lot of the heavy lifting with regards to displaying previews, code etc and it would be a lot of work to re-implement this in a completely bespoke UI. (The custom theme route is also currently very under-documented which doesn’t help)
It seems to make sense to ‘pave the cow paths’ - double down on the 95% use case (customising Mandelbrot) and optimise that over the 5% use case (developing bespoke UIs).
To this end, future releases should concentrate on moving the current web UI serverbuildertheme model in this direction. This would likely involve moving the responsibility for routing and view handling out of the theme and into the web UI server, which would simplify the theme templates significantly and have them act as more traditional simple static ‘view’ templates. This would decrease both the complexity of the the theme setup/configuration and mean that the templates require much less logic within them to handle rendering of components and displaying documentation pages.
The server instance itself should also be made available so that custom Express middleware can be added to extend the server functionality if required.
Fractal currently lacks ways to customise its core parsing behaviour, or to extend the component configuration handling process. The result is that feature requests for additional functionality either have to be added to core, or not implemented at all. In the spirit of trying to keep the main codebase as focussed as possible this would be a key area to work on so that we can try and kick-start a plugin-based ecosystem for Fractal.
Proposed improvements: Add hooks to allow customisation of the core filesystem parsing behaviour, as well as a mechanism for extending the component, docs, sources and collection entities that are exposed via the API.
Related issues: * Alternate contexts (Scenarios) for the same component? · Issue #149
Fractal’s in-built CLI currently has a very limited set of functionality, restricted to starting/stopping the web server and not much else. Given the availability of the API and the potential to build many more useful tasks, this is a shame.
Extending the list of built-in tasks to component scaffolding, renaming of components, ‘doctor’ tasks for identifying potential problems and much more would significantly increase the speed at which component libraries could be assembled and changes to existing components made.
To meaningfully be able to support many of the above changes going forward, the core codebase needs a significant overhaul. The current Fractal implementation suffers from the somewhat haphazard and ‘organic’ process from which it moved from prototype to open source project. This is also currently a pretty major blocker to getting more developers onboard with contributing to the project.
The following areas need to be addressed to make outside contribution easier and to have more confidence in releasing updates (and releasing with more regularity):
Fractal’s un-opinionated nature when it comes to build tools and template languages can also increase the complexity when it comes to less technical users setting up new projects. Some quick-start, pre-built ‘templates’ or generators for a Gulp-based project, a Grunt-based project, etc. would be a great help for getting people who are not interested in customising these aspects themselves up and running quickly.
Currently the Slack channel and Github issues are the only way of communicating with the community regarding upcoming releases, important bug fixes and trying to solicit feedback on proposed features. How can this be improved?
Some thoughts would be:
We also need to provide better contribution guidelines and development information to help people get involved.
This is an ongoing process, but apart from filling in the blanks in the Guide we need to look at how the docs are built and hosted. Currently it’s a pretty manual process but it would be good to open this up so that PRs can be quickly and easily pushed live.
Autogenerating API docs from Docblock comments or similar needs to be investigated as a way to keep these docs in sync with development.
An ‘official’ demo site is still sorely needed, as well as some sort of ‘tips and snippets’ repo/site where useful configuration examples and how-tos can quickly and easily be posted up.
There is a lot of potential work described above, and much of it will require some significant changes to Fractal’s underlying codebase. It will also likely involve some major breaking changes to some parts of the existing Fractal APIs, although keeping compatibility with existing configuration file formats and filesystem/folder structures will be treated as a priority.
However none of the above is set in stone, and much of it may not even make its way into the next major release. Feedback is most welcome, including ideas on what should be prioritised and if any of the above causes people any concerns with regards to the way that they are currently using Fractal.
I’ll shortly be publishing a roadmap of how I see some of the above features fitting into the next few cycles of development, but until them please throw any questions or comments my way :-)
This was originally published on Github.