MigrationToNodeJsExtensions.md

Migrating to Lombiq Node.js Extensions

Please execute the following steps in the given order.

Update your project file

1. Remove all references to Lombiq.Gulp.Extensions and Lombiq.Npm.Targets.
2. Add project and/or package references to Lombiq.NodeJs.Extensions.
3. In case of a project reference, you also need to manually import the .props and .targets files.

<Project Sdk="Microsoft.NET.Sdk.Razor">

+  <Import Condition="'$(NuGetBuild)' != 'true'" Project="..\..\Utilities\Lombiq.NodeJs.Extensions\Lombiq.NodeJs.Extensions\Lombiq.NodeJs.Extensions.props" />
+
<PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
@@ -41,16 +43,16 @@
    <PackageReference Include="OrchardCore.ContentFields" Version="1.4.0" />
</ItemGroup>

-  <Import Condition="'$(NuGetBuild)' != 'true'" Project="..\..\Utilities\Lombiq.Npm.Targets\Lombiq.Npm.Targets.props" />
-  <Import Condition="'$(NuGetBuild)' != 'true'" Project="..\..\Utilities\Lombiq.Npm.Targets\Lombiq.Npm.Targets.targets" />
-
<ItemGroup Condition="'$(NuGetBuild)' != 'true'">
    <ProjectReference Include="..\..\Libraries\Lombiq.HelpfulLibraries\Lombiq.HelpfulLibraries.OrchardCore\Lombiq.HelpfulLibraries.OrchardCore.csproj" />
-    <ProjectReference Include="..\..\Utilities\Lombiq.Gulp.Extensions\Lombiq.Gulp.Extensions.csproj" />
-    <ProjectReference Include="..\..\Utilities\Lombiq.Npm.Targets\Lombiq.Npm.Targets.csproj" />
+    <ProjectReference Include="..\..\Utilities\Lombiq.NodeJs.Extensions\Lombiq.NodeJs.Extensions\Lombiq.NodeJs.Extensions.csproj" />
</ItemGroup>

<ItemGroup Condition="'$(NuGetBuild)' == 'true'">
    <PackageReference Include="Lombiq.HelpfulLibraries.OrchardCore" Version="4.7.0" />
+    <!-- Replace TODO with the latest version number. -->
+    <PackageReference Include="Lombiq.NodeJs.Extensions" Version="TODO" />
</ItemGroup>

+  <Import Condition="'$(NuGetBuild)' != 'true'" Project="..\..\Utilities\Lombiq.NodeJs.Extensions\Lombiq.NodeJs.Extensions\Lombiq.NodeJs.Extensions.targets" />
+
</Project>

Configure Node.js Extensions in package.json

Refer to the documentation on how to configure each part.

Asset copying needs to be manually configurated - there are no magic assets directories in Node.js Extensions anymore.

For an example of such a migration, take a look at the pull request that contained the migration of our Lombiq Data Tables for Orchard Core project to Node.js Extensions, especially the following files:

• Gulp/paths.js
• Gulp/tasks/copy-assets.js
• package.json

Stop tracking the wwwroot folder

This includes removing any .placeholder file that might exist there.

Also ensure that wwwroot is added to the project's .gitignore file. In the standard scenario, no files under wwwroot should be committed to the repository.

Delete Gulpfile.js and any Gulp left-overs

This could be a directory of task scripts, for example.

Delete all node_modules directories

Any project using Node.js Extensions will be using PNPM for package management. In order for PNPM to properly handle packages, it is necessary to clear or delete any affected project's node_modules directory.

One way to achieve the above would be to execute the following PowerShell script:

Get-ChildItem -Filter node_modules -Recurse | Remove-Item -Force -Recurse

Delete package-lock.json, add pnpm-lock.yaml

With the switch from NPM to PNPM, any package-lock.json can be removed from your source repository. Instead, add pnpm-lock.yaml, PNPM's own lockfile, to it.