Walkthrough: Serializing with NuGet and npm

Abstract

How to import serialized items into your solution with NuGet and npm.

You can use package referencing (NuGet and/or npm) to import serialized items into your solution.

This walkthrough describes how to:

Create a package
Create a NuGet package
Create an npm package
Add a package reference

Create a package

To create a package containing Sitecore serialization:

Add a sitecore.json file in the package root. This file contains a modules property pointing to serialization modules files.
Note
Module files are not organized in a specific way in the package to accommodate different patterns.
An example of the package structure:
- Root
  - sitecore.json
  - modules
    items/*/*.module.json
    npm:./packageSrc/npm-resource-package
    nuget:Sitecore.DevEx.NuGetResourcesExample@1.0.0
An example of the sitecore.json file:
```
{
  "modules": [
    "modules/*.module.json"
  ]
}
```
An example of a module file named Sitecore.DevEx.NuGetResourcesExample.module.json:
```
{
  "namespace": "Sitecore.DevEx.NuGetResourcesExample",
  "description": "Content serialization example",
  "items": {
    "includes": [
      {
        "name": "Content",
        "path": "/sitecore/content/home"
      }
    ]
  }
}
```
To check that you set up the package correctly, run the following command:
```
sitecore serialization info
```
You set up the package successfully if the command returns the following message:
```
Sitecore.DevEx.NuGetResourcesExample
Content serialization example
  Subtrees:
    Content: /sitecore/content/home
```

Create a NuGet package

After you have added the sitecore.json file in the package root, you can create a NuGet package.

To create a NuGet package containing Sitecore resources:

Add the PackageName.nuspec file to define the package, for example:

<?xml version="1.0"?>
<package >
  <metadata>
    <id>NugetResourcesExample</id>
    <description>Example NuGet package containing Sitecore resources</description>
    <authors>Sitecore</authors>
    <version>1.0.0</version>
  </metadata>
  <files>
    <!-- the sitecore.json and modules and items must be copied to the package -->
    <file src="NuGetResourcesExample\sitecore.json" target="" />
    <file src="NuGetResourcesExample\sitecore\**" target="sitecore" />
  </files>
</package>

Note

There is no specific location for the PackageName.nuspec file in your project, as long as the file paths are relative to it.

Add any Sitecore resource files that you want to package (module files or serialized items) in the files section of the PackageName.nuspec file.
To build the package, run nuget pack and push it to the NuGet feed of your choice.

Create an npm package

After you have added the sitecore.json file in the package root, you can create a npm package.

To create an npm package containing Sitecore resources:

Add the package.json file to define the package, for example:

{
  "name": "npm-example-package",
  "version": "1.0.0",
  "description": "Sample of providing SIC resources via npm"
}

Open the .gitignore or .npmignore files to check that they do not ignore the resources you want to include automatically in the npm package.

Note

You do not have to build most npm packages before publishing them to the package repository of your choice.

Add a package reference

Important

To use package references, you must have nuget or npm available as a command on your PATH to install the packages during Sitecore CLI operations.

To add a package reference to your solution:

In the sitecore.json file, in the modules property, add an entry for either:
- nuget:<packagename>
- npm:<packagename>
For example:
```
"modules": [
  "local-file-modules/*.module.json",
  "npm:my-package",
  "npm:my-other-package@0.2.0", // version specs allowed per npm install
  "npm:./path/to/local/package", // local package on filesystem
  "nuget:Organization.MyPackage",
  "nuget:Organization.MyOtherPackage@2.1.1", // version specs allowed. No wildcards.
],
```
Note
NuGet package references install using registered package sources on your machine. To specify a custom package source, you can create a NuGet.config file at the root of your repository that contains any custom feeds to resolve your package references.
For further information, see Extend the Command Line Interface with NuGet.

After a package reference is registered, it is automatically installed and parsed for modules during any Sitecore CLI operation that uses modules. You can check the module installation with sitecore ser info or sitecore ser push. Updating modules is automatic based on any version specifications.