Core library for StoreFront components
npm install @storefront/core
StoreFront's core module can be used to start an instance of StoreFront, mount tags to the DOM and register custom tags.
It also contains a number of useful abstractions for the development of custom tags.
This module is meant to be used in a node environment which is bundled for use in the browser.
Use npm or yarn to install in a node project that uses webpack, browserify or similar.
``sh`
npm install --save @storefront/coreor
yarn add @storefront/core
This module can be used both to start an entire StoreFront application,
or to create a new component that registers with your application.
`js
import StoreFront from '@storefront/core';
// start a StoreFront application
const app = new StoreFront({ / config / });
// mount a component
StoreFront.mount('gb-query');
// or
app.mount('gb-query');
`
#### Configuration
* customerId: The only required configuration that must be passed
to start a StoreFront instance
The rest of the configuration can be found in the generated API reference.
The current minimal webpack configuration to load components from @storefront npm packages
and link them with @storefront/core.
`js
// app.js
var StoreFront = require('@storefront/core').default;
require('@storefront/structure');
require('@storefront/query');
new StoreFront({ customerId: 'myCustomer' }).mount('*');
`
`js
// webpack.config.js
module.exports = {
entry: './app',
module: {
rules: [{
test: /\.html$/,
loader: 'html-loader'
}, {
test: /\.css$/,
use: [
'to-string-loader',
'css-loader'
]
}]
}
};
`
Although the supplied development tools do not require ES2015+ to function,
the examples will show them with that syntax for cleanliness
`js
import { tag } from '@storefront/core';
const template = '
@tag('my-component', template)
class MyComponent {
init() {
this.someContent = 'hello world!';
}
}
`
sh
yarn build
`To build an individual package in response to changes within the
directory, run the following command:
`sh
yarn dev
`$3
To test an individual packages, run the following command:
sh
yarn test
`To test an individual package in response to changes within the
and test directories, run the following command:
`sh
yarn tdd
`$3
To lint a package, run the following command:
sh
yarn lint
`To programmatically fix lint errors within a package, run the following command:
sh
yarn lint:fix
`Contributing
Read the contributing file to learn about how to contribute to the StoreFront project.License
StoreFront and its related packages are MIT licensed.Upgrade
$3
In order to address issues with performance stemming from using aliases to render
deeply nested and complex components, a number of changes have been made to that
system and components which use it.
The major conceptual change to the way the system works brings it more inline
with the
/ pattern used in React's Context API
and the language has been changed to match (both for future clarity and to ensure incompatibility
with the previous inefficient alias system).Summary:
-
@alias(aliasName: string) -> @provide(aliasName: string, resolver?: (props, state, aliases) => any)
- -> tag.provide(aliasName: string, resolver?: (props, state, aliases) => any)
- (new!)
- (new!)
- (new!) custom component attribute
- (new!) _props custom component attribute
- (new!) custom component
- (new!) custom component
- (new!) item-props \ prop
- (removed!) "state-finalized" tag lifecycle event
- (removed!) "recalculate-props" tag lifecycle event
- (removed!) "props-updated" tag lifecycle event####
@provide decoratorThe
@alias decorator has been removed in preference for the new @provide decorator.By default, both decorators will register an alias under the name provided
and the value will be the
state of the component.##### ${version} <= v1.39.X
`ts
import { alias } from '@storefront/core';// in TypeScript
@alias('myComponent')
class MyComponent {
state = { myValue: 'Hello, world!' };
}
`js
// or in ES6
@alias('myComponent')
class MyComponent {
constructor() {
this.state = { myValue: 'Hello, world!' };
}
}
`html
{ $myComponent.myValue }
{ $myComponent.myValue }
`html
Hello, world!
`##### ${version} >= v1.40.0
ts
import { provide } from '@storefront/core';// in TypeScript
@provide('myComponent')
class MyComponent {
state = { myValue: 'Hello, world!' };
}
`js
// or in ES6
@provide('myComponent')
class MyComponent {
constructor() {
this.state = { myValue: 'Hello, world!' };
}
}
`Notice that the
decorator has been replaced with a @provide decorator
which, when provided only a single parameter, works the exact same way as
the @alias decorator.`html
{ $myComponent.myValue }
{ $myComponent.myValue }
`Two changes are made to the "consuming" component:
1. if it's not already wrapped in a custom component, any element
can be turned into a simple component with
1. a attribute is added which declares the alias dependencies of
the associated component scope
`html
Hello, world!
`##### alias resolver
In order to allow aliases to change based on the state of the providing component,
the passed either using the
decorator or the tag.provide() method must
be a function with the following signature:`ts
function (props: object, state: object, aliases: object) {
return 'my value';
}
`This function is called with the
, state and aliases of the providing
component every time a new value is required by a consuming component.####
@consume() decoratorWhen creating components using a class, the
@consume() decorator can be used
to statically declare a dependency on an alias. This is similar to using the _consumes
attribute on that component within a template or calling within
that component's init() method.##### ${version} <= v1.39.0
`ts
class CustomComponent {}
`html
{ $myAlias }
`##### ${version} >= v1.40.0
ts
@consumes('myAlias')
class CustomComponent {}
`html
{ $myAlias }
`Note: The important change here is that only components that explicitly
"consume" an alias will be able to access the alias value within their template.
Because riot's scope is tied only to the direct ancestor component this may mean that a complex
component with multiple accesses to an alias may need to be re-thought so that only a single "consumer"
is used and then distributed by passing to child components as props or accessing from nested templates
using
(also sparingly).##### ${version} <= v1.39.0
`html
This is my innermost content: "{ $y }"
`##### ${version} >= v1.40.0
html
This is my innermost content: "{ $y }"
This is my innermost content: "{ $y }"
This is my innermost content: "{ parent.$y }"
`####
and tag.consume()These methods can be called from within the component's
method only
to provide and consume aliases.`ts
class MyComponent {
init() {
this.consume('parentAlias');
this.provide('myAlias', ({ label }, { currentValue }) => ({ label, currentValue }));
// note that aliases passed to the resolver do not include the dollar sign ($) prefix
this.provide('other', (props, state, { parentAlias }) => ({ label, currentValue, ...parentAlias }));
} onBeforeMount() {
// this will throw an exception if called outside of the
init() method
this.provide('myAlias', ({ label }, { currentValue }) => ({ label, currentValue }));
}
}
`ts
class NestedComponent {
init() {
this.consume('myAlias');
} onBeforeMount() {
// this will throw an exception if called outside of the
init() method
this.consume('myAlias');
}
}
`####
custom component attributeThis attribute marks a component as a consumer of one or multiple aliases.
`html
{ $someAlias }
{ $someAlias } and { $otherAlias }
`####
custom component attributeIn lieu of being able to spread props onto a component (such as in JSX) the
_props
attribute has been added. The object passed will be spread as the props of the component
and are overridden by any explicitly passed props.html
`####
and These components have been added to allow for declarative aliasing but are still rough
around the edges as they still introduce a scope and a custom tag into the DOM.
For now, the most useful pattern is to use the
property on a tag
in order to avoid the additional DOM node.`html
{ $someAlias }
{ $someAlias }
{ ... }
{ ... }
`
####
item-props attributeIn order to provide props directly to the
components within
the item-props attribute has been added. This props is passed into
the _props prop of the tags.`html
{ props.a } { item }
- b 1
- b 2
- b 3
`$3
In order to address memory usage concerns a new utility method has been added
to tag instances which automates the cleanup of
event listeners when the
tag is unmounted.##### ${version} <= v1.39.0
`ts
class MyComponent {
init() {
this.flux.on('some_event', this.eventHandler);
// usually no cleanup necessary (only executes once)
this.flux.one('some_event', this.eventHandler);
} onUnmount() {
this.flux.off('some_event', this.eventHandler);
}
}
`##### ${version} >= v1.39.1
ts
class MyComponent {
init() {
// automatically removed on "unmount"
this.subscribe('some_event', this.eventHandler);
// alias for this.flux.one()
this.subscribeOnce('some_event', this.eventHandler);
}
}
``