Moving Fractal forwards

New features and usability improvements

Components

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.

Proposed improvements

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:

• Moving towards a more explicit set of naming conventions for components and their associated files to simplify the parsing process and to be able to more easily move and rename components.
• Supporting multiple, concurrent view template languages - i.e. having the ability to define (for example) Handlebars and Nunjucks versions of a component side by side in your component library.
• Supporting the creation of placeholder components with just a README or graphical mockup of a component which can be viewed in the web UI.
• Supporting multiple component source directories.
• Simplify template engine adapters, look into support for client-side rendering where possible?
• Providing better ways to supply templates with the default context data for their included partials when nesting component templates, without compromising the ability of the view template to be used in a non-Fractal (i.e. production) environment.
• Improving the performance of the filesystem parsing through intelligent caching of unchanged collections/components.

Related issues

• Multiple template engines for components / preview templates (e.g. by file extension) · Issue #191
• Create a better default helper/behavior for including subcomponents · Issue #138
• Feature request: Allow for multiple root level ‘component’ folders · Issue #103
• Support collator templates as well as callback functions · Issue #113
• Enhancement: support for registering multiple file extensions for components · Issue #26

Pages/docs

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.

Proposed improvements

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.

Related issues

• Linking to other components · Issue #125
• Linking component assets in component readme.md · Issue #168

Web UI/theming

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)

Proposed improvements

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.

Related issues

• Add a “preview switcher” to Web UI · Issue #176
• Enabling gzip · Issue #172
• Can the panels shown being customised as per component? · Issue #171
• feature: defining url/slug for preview mode of components · Issue #141

Extensibility

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

Tooling

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.

Proposed improvements

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.

Related issues

• List all render errors · Issue #189
• Give a warning if two components have the same handle/url · Issue #188

Codebase improvements and refactoring

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):

• Modularity: The current codebase is a monolith, which makes contributions and testing much harder. There is plenty of opportunity to extract out of this codebase smaller, more focussed modules and manage these as dependencies instead.
• Testing: The current lack of any real test coverage is a major barrier to being able to release updates with any confidence. New versions of Fractal will need to double down on testing in order to move the project forwards.
• Clarity: The current codebase is an evolved prototype rather than a ‘designed’ piece of software. Now that the aims and feature set are much better understood, work needs to be done to improve the clarity and focus of the code to make it easier for for outside contributors to dive in and help out with the project.

Other

‘First run’ experience

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.

Community communication and contributions

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:

• Move to Gitter (like Slack but publicly browsable). But is this too niche?
• Twitter account for announcements
• A blog for longer form tutorials/release notes?

We also need to provide better contribution guidelines and development information to help people get involved.

Better documentation and examples

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.

In closing

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.