Conversation

trusktr

Continues from PR

Part of

Summary

Convert to ES Modules. Round two (replaces PR #1689)

What kind of change does this PR introduce?

Code style update
Refactor
Docs
Build-related changes

For any code change,

  • Related documentation has been updated if needed
  • Related tests have been updated or tests have been added

Does this PR introduce a breaking change? (check one)

  • Yes
  • No

Applications with build tooling relying on CommonJS may not work anymore. People with no build using the global script method of importing Docsify should not be affected.

Related issue, if any:

#2102

Tested in the following browsers:

  • Chrome
  • Firefox
  • Safari
  • Edge
  • IE

@vercel

The latest updates on your projects. Learn more about Vercel for Git ↗︎

NameStatusPreviewCommentsUpdated (UTC)
docsify-preview✅ Ready (Inspect)Visit Preview✅ 1 resolvedJul 16, 2023 4:58pm

@trusktrtrusktr changed the title initial conversion to ESM initial conversion to ESM, and deletion of CommonJS Jun 25, 2023
@trusktrtrusktr linked an issue Jun 25, 2023that may be closed by this pull request
Get rid of CommonJS module format, use only ES Modules. #2102
Closed
@trusktrtrusktr mentioned this pull request Jun 25, 2023
Closed
@trusktr

@sy-records looks like build:js fails on Vercel, but it works for me locally. Do you see any issue with build:js?

EDIT: I needed to hit "Redploy" without build cache. Now past that error.

@sy-records
> [email protected] css
--
15:16:04.346 | > node build/css -o themes
15:16:04.346 |  
15:16:04.402 | file:///vercel/path0/build/css.js:6
15:16:04.402 | fs.readdir(path.join(__dirname, '../src/themes'), (err, files) => {
15:16:04.403 | ^
15:16:04.403 |  
15:16:04.403 | ReferenceError: __dirname is not defined in ES module scope
15:16:04.403 | This file is being treated as an ES module because it has a '.js' file extension and '/vercel/path0/package.json' contains "type": "module". To treat it as a CommonJS script, rename it to use the '.cjs' file extension.
15:16:04.403 | at file:///vercel/path0/build/css.js:6:22
15:16:04.403 | at ModuleJob.run (node:internal/modules/esm/module_job:194:25)
15:16:04.403 |  
15:16:04.403 | Node.js v18.15.0
15:16:04.420 | ERROR: "build:css" exited with 1.
15:16:04.432 | npm ERR! code 1
15:16:04.432 | npm ERR! path /vercel/path0
15:16:04.433 | npm ERR! command failed
15:16:04.433 | npm ERR! command sh -c npm run build
15:16:04.434 |  
15:16:04.434 | npm ERR! A complete log of this run can be found in:
15:16:04.435 | npm ERR!     /vercel/.npm/_logs/2023-06-25T07_15_41_968Z-debug-0.log
15:16:04.469 | Error: Command "npm install" exited with 1
15:16:04.960 | BUILD_UTILS_SPAWN_1: Command "npm install" exited with 1

@codesandbox-ci

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit eb3706c:

SandboxSource
docsify-templateConfiguration

@trusktr

15:16:04.403 | ReferenceError: __dirname is not defined in ES module scope

Just saw your comment, but I fixed already. :)

It will be nice if we can see builds for all pull requests, because right now the base of this pull request is delete-ssr and this causes the builds to be skipped (f.e. the unit tests).

@trusktr

Ok, I updated test.yml, and now all builds are running! Nice!

@trusktr

We should add a few more tests that currently do not exists while we're at it, to test for backwards compatibilty. For example:

  • test the website loading Docsify from unpkg to ensure that still works
  • test with cdnjs
  • etc

Basically we want to ensure that all people using the standard <script> are not broken. And this will be only a breaking change for people who have a build setup where they import ... from 'docsify', as some tools might break with the new type:module and exports field in package.json. Most users use <script>, and should not be affected.

@trusktr

Tests are almost passing. Darn Windows! Once we're ready, I'll squash with angular commit format.

@trusktr

The build is green!

@trusktr

Looks like Vue mounts broke? See this page at the very bottom: https://docsify-preview-9clr8ye9a-docsifyjs.vercel.app/?vercelThreadId=sWMyo#/configuration?id=vuemounts

EDIT: nevermind. Looks like it already doesn't work from before. For example, this build,

https://docsify-preview-6nln8n898-docsifyjs.vercel.app/#/configuration?id=vuemounts

for pull request #2093 doesn't work.

@trusktr

I pushed one more update to restore deleted example code (I think we should just delete example.test.js files) and ci/codesandbox failed for some reason, but the output looks fine. Looks like a codesandbox bug.

@Koooooo-7

I pushed one more update to restore deleted example code (I think we should just delete example.test.js files) and ci/codesandbox failed for some reason, but the output looks fine. Looks like a codesandbox bug.

Some unit test cases put in example.test.js now. We need refine it with meaningful file name later.

@trusktr

Some unit test cases put in example.test.js now. We need refine it with meaningful file name later.

Roger! I'll take a look, delete only example tests, keep real tests, and rename the files (or move to existing files).

@trusktr
refactor: convert to ES Modules and remove traces of CommonJS except …
62d756c
…in Rollup config because some dependencies are still CommonJS

BREAKING: The new project layout might break in some tooling setups.

We've added an exports field to `package.json` to specify where
statements like `import ... from 'docsify'` will import from, and left
the `main` and `unpkg` fields as-is for backwards compatibility with the
global <script> import method. Most people who use a non-module
`<script>` tag to import Docsify will not notice a difference. Anyone
else who is importing Docsify into a specilized build setup using
`import` statements has a chance of being broken, so we've marked this
as BREAKING.
@trusktr
build: run tests for all pushes, so we can see build status in any pu…
9079393
…ll request and not only for those to main or develop
@trusktr
chore: remove unnecessary example tests
eb3706c
@trusktrtrusktr mentioned this pull request Jun 30, 2023
Merged
9 tasks
@trusktr

I deleted the unnecessary example tests (left the good ones that were in the example files)

Base automatically changed from delete-ssr to develop July 2, 2023 18:34
@trusktr

We should add a few more tests that currently do not exists while we're at it, to test for backwards compatibilty. For example:

  • test the website loading Docsify from unpkg to ensure that still works
  • test with cdnjs
  • etc

Actually we can't really test unpkg or cdnjs without publishing! However, all tests still pass with the global build, and I haven't changed the tests, so this mean everything will work.

When we publish to npm, then https://unpkg.com/docsify or https://unpkg.com/docsify/lib/docsify.min.js will both forward to https://unpkg.com/docsify@5/lib/docsify.min.js, and this will continue to work (same file we use in our tests).

So, all apps using this HTML:

<script src="https://unpkg.com/docsify"></script>

or

<script src="https://unpkg.com/docsify/lib/docsify.min.js"></script>

will not be broken.

Note, as we chatted about previously, there are quite a number of people using the URLs without version numbers:

https://.com/search?q=https%3A%2F%2Funpkg.com%2Fdocsify&type=code

It looks like CDNjs URLs like https://cdn.jsdelivr.net/npm/docsify/lib/docsify.js will continue to work as well, using the same file structure.

So I think we're good here.

In the modernizing issue, I'll write a task for a new deprecation cycle so that we can get people off of the versionless URLs in a reasonable way without suddenly breaking them.

@trusktr

@docsifyjs/core Alright, this is ready to go. Required tests passing (codesandbox build is having a sporadic issue unrelated to Docsify, resource limits being reached, and I currently have no control over that integration that @anikethsaha put in place)

@trusktrtrusktr requested review from Koooooo-7 and a team July 3, 2023 09:16
This was referencedJul 4, 2023
Closed
Open
trusktr
trusktr commented Jul 16, 2023
View reviewed changes
.vscode/launch.json
"args": ["--", "-i", "${relativeFile}", "--testPathIgnorePatterns"],
"runtimeExecutable": "npx",
"runtimeArgs": ["jest"],
"args": ["-i", "${relativeFile}", "--testPathIgnorePatterns"],
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These scripts were out of date. Now you can run them in VS Code! Give it a try!

@trusktr

Alright, per our Discord convo, its going in!

@trusktrtrusktr merged commit c2428f7 into develop Jul 16, 2023
@trusktrtrusktr deleted the es-modules branch July 16, 2023 17:06
Sign up for free to join this conversation on . Already have an account? Sign in to comment

@Koooooo-7 Koooooo-7 Awaiting requested review from Koooooo-7

No one assigned
None yet
None yet
No milestone

Successfully merging this pull request may close these issues.

Get rid of CommonJS module format, use only ES Modules.