conversion to ESM, and deletion of CommonJS

trusktr commented 1 year ago

Continues from PR

https://github.com/docsifyjs/docsify/pull/2105 (review that one first)

Part of

https://github.com/docsifyjs/docsify/issues/2104

Summary

Convert to ES Modules. Round two (replaces PR https://github.com/docsifyjs/docsify/pull/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)

[x] 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:

https://github.com/docsifyjs/docsify/issues/2102

Tested in the following browsers:

[x] Chrome
[x] Firefox
[x] Safari
[x] Edge
[ ] IE

vercel[bot] commented 1 year ago

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

Name	Status	Preview	Comments	Updated (UTC)
docsify-preview	✅ Ready (Inspect)	Visit Preview	✅ 1 resolved	Jul 16, 2023 4:58pm

trusktr commented 1 year ago

@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 commented 1 year ago

> docsify@4.13.0 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[bot] commented 1 year ago

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 eb3706c6c862ed58175e1333d902d52edf617d36:

Sandbox	Source
docsify-template	Configuration

trusktr commented 1 year ago

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 commented 1 year ago

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

trusktr commented 1 year ago

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 commented 1 year ago

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

trusktr commented 1 year ago

The build is green!

trusktr commented 1 year ago

~~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 https://github.com/docsifyjs/docsify/pull/2093 doesn't work.

trusktr commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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

trusktr commented 1 year ago

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://github.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 commented 1 year ago

@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)

trusktr commented 1 year ago

Alright, per our Discord convo, its going in!

docsifyjs / docsify