Vactory Next Package

In this documentation, we will explore the @vactorynext/core package and guide you through upgrading your project to utilize its features.

Why Packaging Core Functionalities

Vactory Next projects feature numerous components and functionalities that remain consistent across various implementations, whether in Vactory or other projects like Bourse, AGR, Micepp, Sonasid, etc. This includes elements such as Contexts, Hooks, Library functionalities, Blocks, and Paragraph components.

Previously, any change, refactoring, or fixing of these elements required MANUAL updates across different projects, which was impractical. To address this, we introduced the @vactorynext/core package. This package serves as a central workspace, allowing for synchronization across projects simply by updating the package.

Is it an NPM Package or a Workspace?

The previous section mentioned that @vactorynext/core is an NPM package while also serving as a central workspace. This dual role is indeed accurate. @vactorynext/core functions as a workspace, similar to the starter and documentation workspaces, but it has also been published as an NPM package.

Why have we taken this approach?

In Vactory Next project, the project is configured to use code from @vactorynext/core located in the local path packages/core. This setup allows developers to make and directly test changes without needing to modify their imports. Conversely, in other projects, they use code from the @vactorynext/core package published on NPM.

In conclusion:

  • In Vactory Next project: all imports from @vactorynext/core are sourced from packages/core workspace.
  • In other Next projects: all imports from @vactorynext/core are sourced from the NPM Package.

How to modify the @vactorynext/core package?

We mentioned that functionalities and components in this core package remain consistent across various projects, but sometimes we might need to modify and fix and add new code to this package. How can I as a VOID Developer do that?

  1. Clone: The change can only be made in the Vactory Next project.
  2. Make Changes Locally:
    • Navigate to the packages/core/src folder in your local repository.
    • Implement your changes or enhancements here.
    • For new path alias folders, ensure to add these in the files array in package.json to include them in the package.
  3. Run Tests:
    • Before committing your changes, run any existing tests to make sure everything still works as expected (dev, build, storybook:dev, storybook:build, lint & docker for the production environment).
  4. Update Documentation:
    • If your changes involve adding new features or modifying existing ones, update the relevant documentation and examples in the README.md or other documentation files.
  5. Commit Your Changes:
    • Commit your changes with a clear and descriptive commit message. This helps others understand the purpose and context of your changes.
  6. Create a Pull Request (PR):
    • Push your changes to your branch and create a pull request against the feature/v3 repository.
    • In the PR description, provide detailed information about your changes. Highlight any important aspects or considerations related to your contribution.
    • Make sure your PR title and description are clear and concise, giving maintainers a good understanding of your contribution.
  7. PR Review:
    • Once submitted, your PR will be reviewed by the maintainers or the package's responsible person.
    • Engage in discussions or make further changes if requested by the reviewers.
  8. Merging and Publishing:
    • After your PR is approved and merged, the package's maintainer will handle publishing a new version with your changes.

What if I'm working on another repo and want to modify the @vactorynext/core package?

When working on another repository, such as the Bourse project, and you wish to modify the @vactorynext/core package, your changes will typically fall into one of two categories:

  1. Modifications Specific to the Bourse Project:
    • If your modification, let's say adding a new hook, is EXCLUSIVELY relevant to the Bourse Project, you should create this hook within the Bourse project’s workspace (for example, apps/bourse).
    • Use and import this hook as you would any other file, using a path alias like "@/hooks".
    • In this scenario, the @vactorynext/core package does not require any modifications for this hook.
  2. Modifications Common to All Next Projects:
    • Firstly, create your new hook as outlined above in the Bourse Project.
    • Next, add this hook to the Vactory Next project by following the steps described in How to modify the @vactorynext/core package? above.
    • Wait until your modifications are reviewed, approved, and published into the @vactorynext/core NPM package. The package maintainer will notify you once it’s published.
    • Update your project’s package to the new version containing your modifications in the Bourse Project.
    • Import these modifications into the Bourse Project, replacing the locally added code from the “Modifications Specific to the Bourse Project” step.

This approach ensures that modifications specific to a single project are kept separate, while enhancements beneficial to all projects are incorporated into the @vactorynext/core package for broader use.

How to use @vactorynext/core in your project

Let’s say you want to use the @vactorynext/core package in your project. What are the steps that you should follow?

Pre-Implementation Phase

Before integrating the @vactorynext/core package into your project, it’s crucial to thoroughly analyze the source code found in packages/core. This step is essential due to several reasons:

  1. Understanding Recent Changes: The @vactorynext/core package has undergone multiple updates, particularly to its functions and components. Familiarizing yourself with these changes will give you a clear picture of the current capabilities and limitations of the package.
  2. Identifying Differences: By examining the source code, you can identify any differences or modifications from previous versions. This understanding is critical for ensuring compatibility with your existing code and for planning the integration process.
  3. Developing an Implementation Strategy: Once you have a clear understanding of the recent changes and the current state of the package, you can strategize on how to effectively implement new functionalities in your project. This strategy should align with your project’s requirements and goals.

For example, consider the usage of the <ParagraphsController /> component within the package:

  • Analyze how this component has evolved in the latest version of the package.
  • Understand its current properties, methods, and their respective functionalities.
  • Consider how these changes affect or enhance the component’s integration into your project.

By taking these steps, you can ensure a smooth and effective implementation of the @vactorynext/core package and its components, such as <ParagraphsController />, into your project.

Before using @vactorynext/core:

apps/starter/components/modules/page/PageNode.jsx

<ParagraphsController
    key={paragraph.id}
    data={paragraph}
    hasAMP={false}
/>

After using @vactorynext/core:

apps/starter/components/modules/page/PageNode.jsx

<ParagraphsController
    key={paragraph.id}
    data={paragraph}
    hasAMP={false}
    isAmp={isAmp}
    DF_DEV_MAPPING={DF_DEV_MAPPING}
    ContainerComponent={Container}
    ImageComponent={Image}
    Widgets={Widgets}
    IconComponent={Icon}
    HeadingComponent={Heading}
    TextComponent={Text}
    TabsComponent={Tabs}
    AccordionComponent={Accordion}
/>

The <ParagraphsController /> component has been enhanced with the addition of multiple properties, including DF_DEV_MAPPING, ContainerComponent, Widgets, and others.

Synchronize Your Project with Vactory Next Starter Project

To keep your project up to date with the latest changes, it's essential to get the latest version of the Vactory Next Starter project. The update includes not only changes to the packages/core but also other files and scripts:

  • apps/starter: This workspace contains the starter files. You can use it as a reference to see how we use @vactorynext/core in its files.
  • scripts/codemod-script.js: A Codemod script to automatically replace your imports with the correct ones from @vactorynext/core and remove duplicates.
  • package.json and yarn.lock

To synchronize your project with the latest changes, follow these steps:

Test if the Package Works Well in Your Project

To ensure you have the latest version of the @vactorynext/core package and to set up its local use in your development environment, follow these steps:

  1. Verify Your Project:

    • Install @vactorynext/core via yarn by running:

      yarn add @vactorynext/core@latest -W

    • Make sure @vactorynext/core was added to the node_modules folder in your root.

  2. Add Necessary Dependencies:

    • Ensure that the peerDependencies in @vactorynext/core/package.json are also present in your root's package.json (Make sure that you have the exact version).
    • Run yarn install to install the necessary dependencies.

  3. Test, Test, Test:

    • To ensure that the integration of @vactorynext/core into your project is successful, test some of its functionalities and components. Try to manually use some of them and experiment with the code.

    • It's essential to test various aspects of the build process, including the standard build (yarn workspace YOUR_WORKSPACE build), development environment for Storybook (yarn workspace YOUR_WORKSPACE storybook:dev), and the Storybook build (yarn workspace YOUR_WORKSPACE storybook:build).

Automatically Replace All Imports Using Codemods Scripts

Now that you're familiar with how @vactorynext/core functions, as well as the necessary file and component refactoring, it's time to use the Codemod scripts. These scripts automate the process of replacing path alias imports in your project with the correct package imports from @vactorynext/core. Here's how to use it:

  1. Install jscodeshift Globally:

    • First, install jscodeshift, a toolkit for running codemods over multiple JavaScript or TypeScript files, globally using npm:

      npm install jscodeshift -g

    • Installing it globally allows you to run jscodeshift from any directory in your terminal.

  2. Run Codemod Scripts:

    • Execute the script by specifying the script path, the file extensions to target (js and jsx in this case), and the paths to the directories containing the files you want to transform.

    • Here's an example command that targets components, pages, themes, and Storybook configuration in the apps/starter directory:

      jscodeshift -t scripts/codemod-script.js --extensions=js,jsx apps/starter/components apps/starter/pages apps/starter/themes apps/starter/.storybook

    • Begin by running the initial script: scripts/codemods/codemod-script.js. After completing the first script, sequentially execute the remaining scripts located in scripts/codemods/. Each script should be run individually.

  3. Verify the Changes:

    • After running the script, check the affected files to ensure that the imports have been correctly replaced.

    • It's a good practice to review the changes made by the script to ensure everything is as expected. Look out for any anomalies or issues that might need manual intervention.

Refactoring Your Code

Running the Codemod script is an important step in automatically updating your project with the @vactorynext/core package without spending hours replacing it yourself. However, manual changes to your files are often necessary to ensure everything functions correctly, particularly in light of the refactoring and enhancements made to packages/core. That is why you should take a serious look at the "Pre-Implementation Phase".

To successfully integrate and adapt to the updates in the @vactorynext/core package, here's a structured approach you can follow:

  1. Run Your Development Server:

    • Start your local development server. This could typically be done using this command:

      yarn workspace YOUR_WORKSPACE dev

  2. Expect Initial Errors:

    • Upon running your development server, you may encounter numerous errors. This is normal and expected given the updates in the @vactorynext/core package.

  3. Avoid Fixing Errors Individually:

    • Instead of addressing the errors one by one, which can be time-consuming and inefficient, take a more systematic approach.

  4. Review Usage of @vactorynext/core in the apps/starter Workspace:

    • Navigate to the packages/core/src folder in Vactory Next workspace. Open each file and identify the functions and components that are exported from it.

    • Examine how these functions and components are utilized in the apps/starter workspace. This will give you a clear idea of how to properly implement them.

  5. Refactor Your Workspace:

    • Apply the insights gained from the apps/starter workspace to your workspace.

    • Refactor your code by updating, adding, changing, or removing properties or arguments in your functions and components to align with the updated @vactorynext/core implementation.

  6. Ensure Comprehensive Update:

    • By following this methodical process, you can ensure that all aspects of your project are updated in accordance with the latest version of @vactorynext/core.

    • This approach minimizes the chances of missing crucial updates and reduces frustration and time spent dealing with individual errors.

  7. Final Testing and Validation:

    • After completing the updates, thoroughly test your project to ensure all changes are functioning as expected and that the integration with the updated package is seamless.

    • Test also in Docker by running: docker compose build and then docker compose up -d.

Hydration ErrorsEnvironment Variables