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 by 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 a SolidJS Core Team maintained project is managed by members of the SolidJS core and ecosystem members. 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

Name	Stage	Primitives	Size	NPM
Browser APIs
clipboard		createClipboard copyToClipboard
event-props		createEventProps
fullscreen		createFullscreen
geolocation		createGeolocation createGeolocationWatcher
permission		createPermission
storage		createStorage createCookieStorage createAsyncStorage createStorageSignal createLocalStorage createSessionStorage
workers		createWorker createWorkerPool createSignaledWorker
event-listener		createEventListener createEventSignal createEventListenerMap createEventStore WindowEventListener DocumentEventListener
mutation-observer		createMutationObserver
Utilities
debounce		createDebounce
i18n		createI18nContext useI18n
props		createProps
script-loader		createScriptLoader
share		createSocialShare
throttle		createThrottle
timer		createTimer
countdown		createCountdown
date-difference		createDateNow createDateDifference
Display & Media
devices		createDevices createMicrophones createSpeakers createCameras
intersection-observer		createIntersectionObserver createViewportObserver createVisibilityObserver
media		createMediaQuery
raf		createRAF
resize-observer		createResizeObserver
tween		createTween
Network
fetch		createFetch
graphql		createGraphQLClient
stream		createStream createAmplitudeStream
Inputs
scroll		createScrollObserver
active-element		createActiveElement createIsElementActive
mouse		createMousePosition createMouseToElement createMouseInElement createMouseOnScreen
Reactivity
composites		createCompositeEffect createCompositeComputed createCompositeMemo createCompositeRenderEffect createModifier

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 approvements 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 guarentee that each is created with the utmost care. Our primitivates are:

1. Documented and follow a consistent style guide
2. Be well tested
3. Small, concise and practical as possible
4. A single primitive for a single purpose
5. As few, if none, dependencies as possible
6. SSR safe entries (or short-circuits where needed) provided
7. Wrap base level Browser APIs
8. Should be progressively improved for future features
9. Be focused on composition vs. isolation of logic
10. Community voice and needs guide roadmap and planning
11. Strong TypeScript support
12. Support for both CJS and ESM
13. 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
• createPageVisibilityObserver

Device

• createBattery
• createAccelerometer
• createGyroscope

Browser

• createURL
• createHistory
• createLocale
• createUpload (https://github.com/Marvinified/use-file-upload)

Network

• createNotification
• createPush
• createConnectionObserver

Inputs

• createGesture (in progress)
• createCompositionObserver (CompositionEvent observer)
• createKeyboard (in progress)
• createForm
• createInput
• createTouch

Utilities

• createWorker (in progress)
• createQueue
• createEffectWhen
• createEventBus