Solid Primitives
A project that strives to develop high-quality, community contributed Solid primitives. All utilities are well tested and continuously maintained. Every contribution to the repository is checked for quality and maintained to the highest degree of excellence. The ultimate goal is to extend Solid's primary and secondary primitives with a set of tertiary primitives.
While Solid Primitives is not officially maintained by the SolidJS Core Team, it is managed by members of the SolidJS core and ecosystem teams. This separation allows the core library to iterate independently while allowing Solid Primitives to remain in-sync with future plans.
Philosophy
The goal of Solid Primitives is to wrap client and server side functionality to provide a fully reactive API layer. Ultimately the more rooted our tertiary primitives are, the more they act as foundation within Solid's base ecosystem. With well built and re-used foundations, the smaller (aggregate tree-shaking benefits), more concise (readability) and stable (consistent and managed testing + maintenance) applications can be overall.
Primitives
Contribution Process
Solid Primitives strives to provide idiomatic Solid principles but also allow room for innovation and experimentation. In a growing community many opinions and patterns merge together to produce a de facto standard. Managing opinions and expectations can be difficult. As a result, in November 2021 Solid Primitives implemented a ratification/approval tracking process roughly modelled on TC39 Proposal Stage Process. The following summarizes these stages briefly:
| Stage | Description |
|---|---|
| X | Deprecated or rejected |
| 0 | Initial submission |
| 1 | Demonstrations and examples |
| 2 | General use (experimental) |
| 3 | Pre-shipping (final effort) |
| 4 | Accepted/shipped |
Any primitive Stage 0-1 should be used with caution and with the understanding the the design or implementation may change. Beyond Stage 2 we make an effort to mitigate changes. If a primitive reaches Stage 2 it's likely to remain an official package with additional approvement until fully accepted and shipped.
Design Maxims
Other frameworks have large and extremely well established ecosystems. Notably React which has a vast array of component and hooks. The amount of choice within the ecosystem is great but often these tools are built as one-offs resulting in often un-tested logic or are designed with narrow needs. Over time the less concise these building blocks are the more they tend to repeat themselves. Our goal with Primitives is to bring the community together to contribute, evolve and utilize a powerful centralize primitive foundation.
All our primitives are meant to be consistent and sustain a level of quality. We guarantee that each is created with the utmost care. Our primitives are:
- Documented and follow a consistent style guide
- Be well tested
- Small, concise and practical as possible
- A single primitive for a single purpose
- As few, if none, dependencies as possible
- SSR safe entries (or short-circuits where needed) provided
- Wrap base level Browser APIs
- Should be progressively improved for future features
- Be focused on composition vs. isolation of logic
- Community voice and needs guide road map and planning
- Strong TypeScript support
- Support for both CJS and ESM
- Solid performance!
Compound vs. Isolated Primitives
Each primitive is designed with composition in mind. To align with the goal of being small and concise a major rule to designing our primitives is deciding if the interface for primitives should be: composable or segmented. For this reason every API is intricately studied and considered to be composed (stacked with features) or composed into smaller units.
Designing our primitives in this manner allows for better tree shaking and very layering complexity as needed. Only ship what you have to by picking from existing primitives as your foundational building blocks.
Lerna CLI Helpers
This package comes with a number of support utilities built with Lerna Scripts.
yarn ls updateReadme- This will update the list of primitives by inspecting individual packages.yarn ls createPrimitive name- A helper to setup a primitive template package.
Planned Primitives
Display & Media
- createDragAndDrop
Device
- createBattery
- createAccelerometer
- createGyroscope
Browser
- createHistory
- createWebShare (https://developer.mozilla.org/en-US/docs/Web/API/Navigator/share)
- createLocale
- createUpload (https://github.com/Marvinified/use-file-upload)
Network
- createNotification
- createPush
- createConnectionObserver
Inputs
- createGesture (in progress)
- createCompositionObserver (CompositionEvent observer)
- createKeyboard
- createForm
- createInput
- createTouch
Utilities
- createWorker (in progress)
- createQueue
- createEffectWhen