# yFiles for HTML Optimizer

Use this tool to minimize and obfuscate your yFiles for HTML applications.

The optimizer will minimize/obfuscate the public API of the yFiles module files, as well as
yFiles API usages in application sources, increasing startup and runtime performance.

Note that this tool is meant to be used in production builds. The resulting yFiles module files will be tailor-made to the yFiles API usages in the application sources that were processed along with
the yFiles modules.

We highly recommend optimizing the yFiles for HTML library before deploying your application to a public web server to reduce the download size of the library for the end user. Note that, at the time of writing, you are not required to use the optimization step for the standard yFiles SLA.

## Obfuscation Excludes

The optimizer might replace non-yFiles API calls that share a name with a yFiles member. Add those
names to the `blacklist` option to keep them unchanged in both the yFiles modules and application
sources.

- Use scope-local `@yjs:keep` comments to exclude these members from obfuscation in a particular scope. This is the preferred approach, because the excluded names will still be obfuscated in yFiles modules and all other scopes.

  ```js
  // @yjs:keep = install,apply
  function my() {
    // "install" and "apply" will not be obfuscated within this scope
    someAPI.install()
    someAPI.apply()
  }

  // @yjs:keep
  function my() {
    // No names will be obfuscated within this scope at all
    //...
  }
  ```
- Currently, `@yjs:keep` does not work with [Vite](https://vite.dev): Comments are removed by Vite before presenting the sources to the optimizer.


## Options

- `safeMode` (default: `false`): Enable `safeMode` to prevent the optimizer from adjusting any names in non-yFiles code.

  The default behavior of the optimizer is to obfuscate the names of all yFiles library members and adjust the corresponding occurrences in your source code. When you use a third-party library that uses member names that also exist in the yFiles API, it can happen that these third-party library calls in your sources are accidentally renamed. In general, we recommend adding these member names to the optimizer's `blacklist`, or use [Obfuscation Excludes](#obfuscation-excludes) to prevent the optimizer from renaming them. However, if it's hard to find out which
  exact member names would have to be excluded from obfuscation in your project, you can enable `safeMode` to prevent renaming of any yFiles members that are used in your code. That way, only unused yFiles members will be obfuscated in the yFiles library modules and your sources will be left untouched.

- `blacklist` (default: `[]`): An array of names that should never be renamed by the optimizer. See [Obfuscation Excludes](#obfuscation-excludes)
- `logLevel` (default: `"info"`): One of "error", "warn", "info", "verbose", "debug", "silly".

  Note that with logLevel "debug" or finer, a `yworks-optimizer-mappings.json` file will be created in the working directory that contains the mappings of unobfuscated to obfuscated yFiles member names. These mappings can help to debug the obfuscated code.

- `obfuscateBabelSafePublicFields` (default: `true`) Whether the optimizer should try to obfuscate calls of babel's `_defineProperty()` helper. With this option enabled, the optimizer will try to detect usages like `_defineProperty(item, "propertyName", value)` and rename the `"propertyName"` if it matches a yFiles member. Note that this behavior could erroneously rename strings in your application. If you find unwanted obfuscated strings in the generated output, try disabling this option. You can also set the `logLevel` to `"debug"` and watch for "Renaming possible babel defineProperty call" messages. For details about configuring the babel output of public class fields, please see https://babeljs.io/docs/en/assumptions#setpublicclassfields

## Rolldown Plugin

The plugin uses the Rolldown plugin API. It performs a collection build followed by a fresh
optimized build, so place it after plugins that produce JavaScript. 

It supports direct Rolldown builds and Vite 8 production builds. On Vite, the second pass invokes
Vite again so Vite owns HTML, stylesheet, worker, and asset handling. Be careful when combining the plugin with other non-standard plugins and carefully test the outputs.

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import optimizer from '@yworks/optimizer/rolldown-plugin'

export default defineConfig({
  plugins: [optimizer()]
})
```

```ts
import { rolldown } from 'rolldown'
import optimizer from '@yworks/optimizer/rolldown-plugin'

const bundle = await rolldown({
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
    format: 'cjs'
  },
  plugins: [optimizer({ logLevel: 'info' })]
})
await bundle.write({ file: 'bundle.js', format: 'es' })
```

### Plugin Options

Options supported by the weback, rollup, and Rolldown plugin in addition to the optimizer options explained above:

- `ignore` An array of [minimatch-glob](https://www.npmjs.com/package/minimatch) patterns or regexps specifying files that should be ignored by the optimizer. Note that the path separators are not normalized for regexp matching, i.e., on windows, `/\\ignoreme.js/` would match, but `/\/ignoreme.js/` would not.

  This option can be used when some source files contain language features that are not supported by the optimizer (e.g. dynamic imports).

  Use this option to ignore only files that do not contain any yFiles code. If the ignored files contain yFiles code, this code will not work with the optimized library.

- `shouldOptimize` An function that determines whether a particular module should be optimized. The default `shouldOptimize` function will exclude all node_modules from optimization.
  Example:

  ```js
  // Rolldown/Vite
  optimizer({
    shouldOptimize({ id }) {
      return id.includes('node-module-that-uses-yfiles') || !id.includes('node_modules')
    }
  })
  ```

 ```js
  // webpack.config.js
  const WebpackOptimizerPlugin = require('@yworks/optimizer/webpack-plugin')

  new WebpackOptimizerPlugin({
    shouldOptimize(module) {
      return (
        /node-module-that-uses-yfiles/.test(module.resource) ||
        !/node_modules/.test(module.resource)
      )
    }
  })
  ```

  ```js
  // rollup.config.mjs
  import RollupOptimizerPlugin from '@yworks/optimizer/rollup-plugin'

  new RollupOptimizerPlugin({
    shouldOptimize({ id }) {
      return id.includes('node-module-that-uses-yfiles') || !id.includes('node_modules')
    }
  })
  ```

## API

```js
const { optimize } = require('@yworks/optimizer')

// libModules: [{source: sourceOfYFilesModuleA}, ...]
// sourceFiles: [{source: appSourceA}, ...]

const optimized = optimize(libModules, sourceFiles, {
  blacklist: [],
  logLevel: 'warn'
})

// optimized:
// {
//    libModules: [{
//                    source: sourceOfYFilesModuleA
//                    result: optimizedYFilesModuleA
//                 }, ...]
//    sourceFiles: [{
//                    source: appSourceA
//                    result: optimizedAppSourceA
//                 }, ...]
// }
```

The optimized sources are attached to the same objects passed to the optimizer,
so additional information (e.g. destination paths) on these objects is not
lost.

## Examples

Please see your [yFiles for HTML](https://www.yfiles.com/the-yfiles-sdk/web/yfiles-for-html) package for example usages of the optimizer.

## License

[MIT](LICENSE) © [yWorks GmbH](http://www.yworks.com)