nextjs-effector
v0.52.0
Published
High-level effector.js bindings for Next.js framework
Downloads
72
Readme
Navigation
Installation
yarn add nextjs-effector @effector/next effector-react effector
Usage
Examples
- Test App - used for testing the
nextjs-effector
library. You can find some architecture notes in README.
Initial setup
First, add effector/babel-plugin
to your .babelrc
:
{
"presets": ["next/babel"],
"plugins": ["effector/babel-plugin"]
}
By doing that, all our Effector units will be created with sid
constant, which is unique and stable between the server and the client, so we can safely serialize store values for sending to the client.
You can also try out the official @effector/swc-plugin
, which is still in early beta as the whole SWC-plugins system itself.
Finally, enhance your App
:
/* pages/_app.tsx */
import App from "next/app";
import { withEffector } from "nextjs-effector";
// Passing effector-react exports is required to access the Scope
export default withEffector(App);
After that, the App
will be wrapped in Effector's Scope Provider. The withEffector
function uses @effector/next
under the hood, which handles all of Next.js caveats and special requirements for us. This way you can focus on writing a business logic without thinking about the problems of integrating Effector into your Next.js application.
Main Concepts
There are 2 types of data in any application:
- Shared - used on almost every page (translations, logged user info)
- Specific - used only in the relevant pages (post content on post page, group info on group page)
Usually, we want these conditions to be met:
- The shared data is loaded once in the application lifecycle (expect for manual update)
- The specific data is loaded on each navigation between the pages
- No shared events boilerplate on every page
Assume we have the following Effector events:
/* Needed everywhere */
export const loadAuthenticatedUser = createEvent();
export const loadTranslations = createEvent();
/* Needed only on the Post page */
export const loadPostCategories = createEvent();
export const loadPostContent = createEvent();
Let's group them into shared and specific:
export const appStarted = createEvent();
export const postPageStarted = createEvent();
sample({
clock: appStarted,
target: [loadAuthenticatedUser, loadTranslations],
});
sample({
clock: postPageStarted,
target: [loadPostCategories, loadPostContent],
});
We want the appStarted
to be called once in the application lifecycle and the postPageStarted
to be called on requesting/navigating to the Post page. nextjs-effector
library provides a 2-level GIP factory to cover this case:
export const createGIP = createGIPFactory({
// Will be called once
sharedEvents: [appStarted],
});
PostPage.getInitialProps = createGIP({
// Will be called on visiting PostPage
pageEvent: postPageStarted,
});
Also, the library provides createGSSPFactory
for getServerSideProps
and createGSPFactory
for getStaticProps
. They have almost the same API, but both of them run sharedEvents
on each request / static page generation.
Factories
getInitialProps
(server and client-side)
getInitialProps
is easier to work with and doesn't require executing the shared logic on each request, including navigation between pages.
/*
* 1. Create events
* GIP accepts the events with "PageContext" or "void" payload types
*/
export const appStarted = createEvent();
export const appStarted = createEvent<PageContext>();
export const pageStarted = createEvent();
export const pageStarted = createEvent<PageContext>();
export const pageStarted = createEvent<PageContext<Props, Params, Query>>();
/*
* 2. Create GIP factory
* The place depends on your architecture
*/
export const createGIP = createGIPFactory({
// Will be called once:
// - Server side on initial load
// - Client side on navigation (only if not called yet)
sharedEvents: [appStarted],
// Allows specifying shared events behavior
// When "false", the shared events run like pageEvent
runSharedOnce: true,
// Allows customizing server-side Scope creation process
// By default, the library just uses fork(), like below
// But you can fill the stores in scope with your values (cookies, for example)
createServerScope: () => fork(),
// The second argument in https://effector.dev/docs/api/effector/serialize
serializeOptions: { ... },
// You can define your custom logic using the "customize" function
// It's run after all events are settled but before Scope serialization
// So, here you can safely call allSettled
async customize({ scope, context }) {
// You can also return nothing (there will be no impact on props in this case)
return { /* Props */ };
},
});
/*
* 3. Create GIP
* Usually, it's done inside the "pages" directory
*/
Page.getInitialProps = createGIP({
// Will be called on each page visit:
// - Server side on initial load
// - Client side on navigation (even if already called)
pageEvent: pageStarted,
// The same as on factory level
async customize({ scope, context }) { ... },
});
getServerSideProps
(only server-side)
For everyday cases, we recommend using getInitialProps
instead. But getServerSideProps
may be useful in some edge cases like executing logic with heavy computations, or accessing the data available only on the server side.
/*
* 1. Create events
* GSSP accepts the events with "PageContext" or "void" payload types
*/
export const appStarted = createEvent();
export const appStarted = createEvent<PageContext>();
export const pageStarted = createEvent();
export const pageStarted = createEvent<PageContext>();
export const pageStarted = createEvent<PageContext<Props, Params, Query>>();
/*
* 2. Create GSSP factory
* The place depends on your architecture
*/
export const createGSSP = createGSSPFactory({
// Will be called on the first request and each page navigation (always on the server side)
sharedEvents: [appStarted],
// The second argument in https://effector.dev/docs/api/effector/serialize
serializeOptions: { ... },
// You can define your custom logic using the "customize" function
// It's run after all events are settled but before Scope serialization
// So, here you can safely call allSettled
customize({ scope, context }) {
// You can omit the "props" field (there will be no impact on props in this case)
return { /* GSSP Result */ };
},
});
/*
* 3. Create GSSP
* Usually, it's done inside the "pages" directory
*/
export const getServerSideProps = createGSSP({
// Will be called on each page navigation (always on the server side)
// Always called after shared events
pageEvent: pageStarted,
// The same as on factory level
customize({ scope, context }) { ... },
});
getStaticProps
(only server-side)
Recommended for static pages.
/*
* 1. Create events
*/
export const appStarted = createEvent();
export const appStarted = createEvent<StaticPageContext>();
export const pageStarted = createEvent();
export const pageStarted = createEvent<StaticPageContext>();
export const pageStarted = createEvent<StaticPageContext<Props, Params>>();
/*
* 2. Create GSP factory
* The place depends on your architecture
*/
export const createGSP = createGSPFactory({
// Will be called on each page generation (always on the server side)
sharedEvents: [appStarted],
});
/*
* 3. Create GSP
* Usually, it's done inside the "pages" directory
*/
export const getStaticProps = createGSP({
// Will be called on each page generation (always on the server side)
pageEvent: pageStarted,
// The second argument in https://effector.dev/docs/api/effector/serialize
serializeOptions: { ... },
// You can define your custom logic using the "customize" function
// It's run after all events are settled but before Scope serialization
// So, here you can safely call allSettled
// Important: due to complex types, this method is not available on factory level like in GIP and GSSP
customize({ scope, context }) {
// You can omit the "props" field (there will be no impact on props in this case)
return { /* GSP Result */ };
},
});
Advanced Page Events Usage
usePageEvent
(useful on the client side)
Executes the provided Event<void> | Event<PageContext>
on the client side.
The hook may be useful for the getStaticProps
cases - it allows to keep Next.js optimization and request some user-specific global data at the same time.
The second parameter is options to enhance the event using enhancePageEvent
.
Usage:
const Page: NextPage<Props> = () => {
usePageEvent(appStarted, { runOnce: true });
return <AboutPage />;
};
export const getStaticProps: GetStaticProps<Props> = async () => {
/* ... */
};
export default Page;
enhancePageEvent
(manual flow control)
Wraps your event and adds some logic to it.
The enhanced event can be safely used anywhere.
It doesn't cause any changes to the original event - you may use it just as before.
const enhancedEvent = enhancePageEvent(appStarted, {
// Works like the "runSharedOnce" option in GIP fabric, but for the single event
// This option applies to both client and server environments:
// If the enhanced event was called on the server side, it won't be called on the client side
runOnce: true,
});
Utility functions
/*
* PageContext has the "env" field with "client" or "server" value,
* so you can determine the environment where the code is executed
*
* The library provides useful types and type-guards for these purposes
*/
import {
isClientPageContext,
isServerPageContext,
ClientPageContext,
ServerPageContext
} from 'nextjs-effector'
const pageStartedOnClient = createEvent<ClientPageContext>()
const pageStartedOnServer = createEvent<ServerPageContext>()
sample({
source: pageStarted,
filter: isClientPageContext,
target: pageStartedOnClient
})
sample({
source: pageStarted,
filter: isServerPageContext,
target: pageStartedOnServer
})
sample({
source: pageStartedOnServer,
fn: (context) => {
// You can access "req" and "res" on the server side
const { req, res } = context
return req.cookie
}
})
/*
* GSP accepts the events with the "StaticPageContext | void" payload
* Unlike PageContext, the StaticPageContext doesn't include query
* and some other properties
*/
export const appStarted = createEvent<StaticPageContext>()
export const pageStarted = createEvent<StaticPageContext>()
export const pageStarted = createEvent<StaticPageContext<Props, Params>>()
/*
* Also, the library exports some utility types
*/
type PageEvent<...> = Event<PageContext<...>>
type StaticPageEvent<...> = Event<StaticPageContext<...>>
type EmptyOrPageEvent<...> = PageEvent<...> | Event<void>
type EmptyOrStaticPageEvent<...> = StaticPageEvent<...> | Event<void>
Recipes
Cookies
You can use createServerScope
to set cookies before executing any logic:
export const createGIP = createGIPFactory({
sharedEvents: [appStarted],
createServerScope: (context) => {
return fork({
values: [[$cookies, context.req?.headers.cookie ?? ""]],
});
},
});
Also, you can access the req
object in effector logic by using isServerContext
import { isServerPageContext } from "nextjs-effector";
sample({
source: appStarted,
filter: isServerPageContext,
fn: (context) => context.req.cookie,
target: $cookies,
});
Common Questions
Where should I call createGIPFactory / createGSSPFactory / createGSPFactory?
The place depends on your architecture. But one thing is certain - creating factories on each page is a really bad idea. They are designed to simplify and encapsulate the repeated logic parts.
For example, with Feature Sliced Design
you might consider creating a layouts
layer, which can be used to create reusable page layouts and factories.
How are multiple customize work?
GIP:
- Execute factory-level
customize
and save result - Execute page-level
customize
and save result - Merge results (page-level priority is higher)
- Merge
nextjs-effector
props inside and return the result from GIP
GSSP:
- Execute factory-level
customize
and save result - It has
redirect
field? Return the result from GSSP - It has
notFound
field? Return the result from GSSP - Execute page-level
customize
and save result - It has
redirect
field? Return the result from GSSP - It has
notFound
field? Return the result from GSSP - Deep merge results (page-level priority is higher)
- Merge
nextjs-effector
props inside and return the result from GSSP
Why in GSSP are the shared events called on each request?
getServerSideProps
, unlike the getInitialProps
, is run only on the server side. The problem is that the pageEvent
logic may depend on globally shared data. So, we need either to run shared events on each request (as we do now), or get this globally shared data in some other way, for example by sending it back from the client in a serialized form (sounds risky and hard).
Also, to check if shared events need to be executed, we should either ask it from the client or persist this data on a server. Both ways sound hard to implement.
That's why getInitialProps
is the more recommended way to bind your Effector models to the Page lifecycle. When navigating between pages, it runs on the client side, so we can easily omit the app event execution.
I need to run sharedEvents and pageEvent in parallel. How can I do that?
You can create GIP / GSSP fabric without sharedEvents
, and define the flow manually:
const createGIP = createGIPFactory();
Page.getInitialProps = createGIP({
pageEvent: pageStarted,
});
sample({
source: pageStarted,
target: appStarted,
});
Also, you can use enhancePageEvent
to run specific events only once in the application lifecycle.
What do I do if there are bundling issues?
Since Next.js 12 ESM imports are prioritized over CommonJS imports. While CJS-only dependencies are still supported, it is not recommended to use them, as those can lead to library doubles in the bundle and really weird bugs.
You can read about it here
In case when there is a CommonJS-only dependency, which uses Effector and you absolutely need it and the author can't fix it - you can copy the library to your project as the last resort measure.
How to
Copy the
src
folder contents into your project, for example intosrc/nextjs-effector
Create the alias using tsconfig.json:
{ "compilerOptions": { "baseUrl": "./", "paths": { "nextjs-effector": ["./src/nextjs-effector"], "nextjs-effector/*": ["./src/nextjs-effector/*"] } } }
Contributing
- Fork this repo
- Use the Regular flow
Please follow Conventions
Maintenance
The dev branch is main
- any developer changes are merged in there.
Also, there is a release/latest
branch. It always contains the actual source code for release published with the latest
tag.
All changes are made using Pull Requests - the push is forbidden. PR can be merged only after successful test-and-build
workflow checks.
When PR is merged, the release-drafter
workflow creates/updates a draft release. The changelog is built from the merged branch scope (feat
, fix
, etc) and PR title. When the release is ready - we publish the draft.
Then, the release
workflow handles everything:
- It runs tests, builds a package, and publishes it
- It synchronizes the released tag with the
release/latest
branch
Regular flow
- Create feature branch
- Make changes in your feature branch and commit
- Create a Pull Request from your feature branch to
main
The PR is needed to test the code before pushing it to therelease
branch - If your PR contains breaking changes, don't forget to put a
BREAKING CHANGES
label - Merge the PR in
main
- All done! Now you have a drafted release - just publish it when ready
Prerelease flow
- Assume your prerelease tag is
beta
- Create
release/beta
branch - Create feature branch
- Make changes in your feature branch and commit
- Create a Pull Request from your feature branch to
release/beta
The PR is needed to test the code before pushing torelease
branch - Create a GitHub release with a tag like
v1.0.0-beta
, pointing torelease/beta
branch
For the nextbeta
versions use semver build syntax:v1.0.0-beta+1
- After that, the
release
workflow will publish your package with thebeta
tag - When the
beta
version is ready to becomelatest
- create a Pull Request fromrelease/beta
to themain
branch - Continue from the Regular flow's #5 step
Conventions
Feature branches:
- Should start with
feat/
,fix/
,docs/
,refactor/
, etc., depending on the changes you want to propose (see pr-labeler.yml for a full list of scopes)
Commits:
- Should follow the Conventional Commits specification
Pull requests:
- Should have a human-readable name, for example: "Add a TODO list feature"
- Should describe changes
- Should have correct labels